Move the example config to configs/, delete scripts/ and CONVENTIONS.md (closes #97)

config.example.yml moves unchanged to configs/config.example.yml, the
directory REPO_POLICIES.md names for configuration examples. README.md,
the comments in internal/config/config.go and the startup error for the
placeholder signing key name the new path. scripts/manual-test.sh and
its directory are deleted. The handler tests in internal/handlers cover
every check it made except two: fetching a real image from the internet,
and a URL made on the generator page with a ttl answering 410 once the
ttl has passed (#199).
CONVENTIONS.md, a reformatted copy of the Go HTTP server conventions, is
deleted, as REPO_POLICIES.md links the canonical document.

Model: opus-5-5

configs/config.example.yml

@@ -0,0 +1,150 @@
+# Pixa Example Configuration
+#
+# Every key can also be set by an environment variable, which wins over
+# this file: PIXA_ plus the key in upper case, with "." written as "_"
+# (state_dir is PIXA_STATE_DIR, metrics.username is
+# PIXA_METRICS_USERNAME). The one exception is port, which is set by
+# PORT. In a variable, a list is comma-separated. A variable named in
+# this file's env: section is set while the file loads, so it overrides
+# both the environment the process was started with and this file's own
+# key.
+#
+# Durations are Go duration strings such as 30s or 2m and must be
+# positive; a bare number has no unit and aborts startup. Sizes are a
+# whole number of bytes.
+#
+# A key left out takes the default its comment gives.
+
+# Port to listen on (default: 8080)
+port: 8080
+
+# Debug logging and plain-HTTP local development (default: false)
+debug: false
+
+# While true, the image routes (/v1/image/ and /v1/e/) answer every request
+# for an image with 503 and a Retry-After header. The health check keeps
+# answering 200 and reports maintenance_mode as true. It stays 200 because
+# the image's Docker HEALTHCHECK requests it: a 503 there would make the
+# container unhealthy, and upaas marks a deploy failed when its container is
+# unhealthy. (default: false)
+maintenance_mode: false
+
+# Data directory for SQLite database and cache files
+# (default: /var/lib/pixa)
+state_dir: ./data
+
+# SQLite database URL (default:
+# file:<state_dir>/state.sqlite3?_pragma=journal_mode(WAL)). pixa adds
+# _pragma=busy_timeout(5000) to it. An empty value aborts startup; leave the
+# key out to use the default.
+# db_url: "file:./data/state.sqlite3?_pragma=journal_mode(WAL)"
+
+# Image proxy settings
+# HMAC signing key for URL signatures (required, at least 32 characters)
+# Generate with: openssl rand -base64 32
+signing_key: "CHANGE_ME_generate_with_openssl_rand_base64_32"
+
+# Hosts that don't require signatures (default: none)
+# Use "." prefix for wildcard subdomain matching (e.g., ".example.com" matches "cdn.example.com")
+allowlist_hosts:
+  - s3.sneak.cloud
+  - static.sneak.cloud
+  - sneak.berlin
+  - github.com
+  - user-images.githubusercontent.com
+
+# Additional CIDR ranges to refuse when fetching upstream, extending the
+# SSRF protection. These are added to the always-enforced built-in ranges
+# (loopback, RFC 1918 private, link-local, CGNAT, benchmark, NAT64, and
+# similar), never replacing them. Each entry must be a valid CIDR in IPv4
+# or IPv6 form; an invalid entry aborts startup. (default: none)
+# blocked_networks:
+#   - 100.64.0.0/10
+#   - 2001:db8::/32
+
+# CIDR ranges of the reverse proxies in front of pixa. X-Forwarded-For
+# is believed only when the direct peer is inside one of these ranges;
+# the client address in the access log and login records is then the
+# rightmost forwarded entry that is not itself a trusted proxy. A client
+# connecting directly (peer outside these ranges) cannot spoof its
+# address: the header is ignored and the peer address is used. When
+# omitted, this defaults to the RFC 1918 private ranges (10.0.0.0/8,
+# 172.16.0.0/12, 192.168.0.0/16), since pixa is deployed behind a proxy on
+# a private network. An explicitly empty list ([]) trusts no one; an
+# explicit list replaces the default. An invalid CIDR aborts startup.
+# Uncomment to override the defaults with the address pixa sees for
+# requests that come through your proxy. That is not always the proxy's own
+# address: a proxy on the Docker host that connects over 127.0.0.1 is seen
+# as the gateway of the container's Docker network (172.17.0.1 on the
+# default bridge), and one that connects through another host address is
+# seen with that address. To be sure, look it up in the request log as the
+# trusted_proxies entry in README.md describes.
+# trusted_proxies:
+#   - 10.0.0.0/8
+#   - 2001:db8::/32
+
+# Allow HTTP upstream (only for testing, always use HTTPS in production)
+# (default: false)
+allow_http: false
+
+# Maximum concurrent connections per upstream host (default: 20)
+upstream_connections_per_host: 20
+
+# Maximum concurrent connections to all upstream hosts together, on top of
+# the per-host limit (default: 64). A fetch holds its connection until its
+# image has been processed. A fetch that finds none free waits up to 10
+# seconds for one, and if none frees up the request is answered 503, unless
+# downstream_timeout has ended first.
+upstream_connections: 64
+
+# Maximum number of images decoded and encoded at once (default: the
+# number of CPUs pixa can use, which follows a container's CPU limit). A
+# request that finds none free waits up to 10 seconds for one, and if none
+# frees up it is answered 503, unless downstream_timeout has ended first.
+# max_concurrent_processing: 4
+
+# Time allowed for one fetch from an upstream host (default: 30s)
+upstream_fetch_timeout: 30s
+
+# Largest upstream response accepted, in bytes, at most 1073741824
+# (1 GiB) (default: 52428800, 50 MiB)
+upstream_max_response_size: 52428800
+
+# Time allowed for answering one client request (default: 60s). The
+# upstream fetch counts toward it, and so do the waits for an upstream
+# connection and for a processing slot (up to 10 seconds each), so keep it
+# longer than upstream_fetch_timeout plus 20 seconds.
+downstream_timeout: 60s
+
+# The origin a browser lets read the responses of the image routes,
+# /v1/image/ and /v1/e/, sent as the CORS Access-Control-Allow-Origin
+# header; no other route sends it. "*" (the default) is any site;
+# otherwise one http or https origin such as https://example.com, whose
+# host is a lowercase host name (letters, digits, hyphens and dots, with a
+# letter in its last part) or an IP address (IPv6 in brackets, in its
+# shortest form), with an optional port 1-65535 that has no leading zero
+# and is not the scheme's default. Any other value, including another
+# scheme such as a browser extension's, aborts startup.
+access_control_allow_origin: "*"
+
+# Maximum disk cache size in bytes. Explicit values are used exactly as
+# given; 0 disables the disk cache entirely (every request fetches and
+# processes uncached). When omitted, the default is 75% of the sum of
+# the free space on the filesystem containing <state_dir>/cache/ and
+# the bytes of images the cache already holds, worked out at startup,
+# with a minimum of 500 MiB.
+# cache_max_bytes: 10737418240
+
+# Sentry DSN for error reporting (default: empty, which turns it off)
+sentry_dsn: ""
+
+# Username and password for /metrics, set together (default: unset). Metrics
+# are measured and /metrics is served only when both are set.
+# metrics:
+#   username: "admin"
+#   password: "secret"
+
+# Environment variables set while this file loads, as described at the top
+# (default: none)
+# env:
+#   PIXA_DEBUG: "true"