feat: Gateway-API as an alternative to the Ingress in five annotation charts

Group 2 of the #114 sweep: the charts whose behaviour hangs off an nginx
annotation - calibre-web-automated, outline, paperless-ngx, zipline
(proxy-body-size) and freesailarr (rewrite-target).

Each gets the form the pilot (cyberchef, PR #115) fixed and group 1 (PR #116)
repeated: an httpRoute block off by default, a template rendering ONLY an
HTTPRoute with parentRefs - no Gateway, no gatewayClassName, no Certificate, no
implementation-specific policy object - render aborts on both modes at once
(naming both value paths), on an empty parentRefs and on a missing hostname,
empty hostnames meaning [ingress.domain], a schema entry closed against unknown
keys with an open parentRef definition, and a NOTES.txt that names the active
mode and what the mode costs.

Minor, additive, defaults unchanged: `helm template` with each chart's CI values
is byte-identical to origin/main for all five.

The upload limit is DOCUMENTED, not rebuilt (decision 2 of the issue). The
Gateway API knows no body size; a policy object would bind the chart to one
implementation. So the Gateway branch of NOTES.txt says, per chart and in the
chart's own terms, that the value is NOT ENFORCED and names where to set it: an
e-book library (calibre), an upload service (zipline), the web-UI half of the
document intake while the consume directory keeps no limit at all (paperless),
and the open #12 pair (outline).

Four findings that were not in the plan, each argued in the file it changes:

  freesailarr gated freesailarr.sharedIngressApps on ingress.enabled, and that
  list is read by the <APP>__SERVER__URLBASE variables as well as by the routing
  objects. In Gateway mode it would have come out EMPTY while the route served
  radarr, sonarr and prowlarr under their prefixes: UrlBase unset, assets and API
  calls linked at the host root, broken UI behind a Ready pod. The helper's two
  guards (seerr/mediathekarr only at "/", no duplicate paths) would have gone
  unenforced there too. Fixed with freesailarr.published (ingress.enabled OR
  httpRoute.enabled) - the same shape as sure.publishedOverTls in group 1, and
  identical to ingress.enabled while httpRoute.enabled is false. Measured: on
  origin/main with ingress.enabled: false the render emits ZERO URLBASE
  variables; with this change in Gateway mode it emits three.

  paperless-ngx was the last chart in the repository rendering its Ingress
  UNCONDITIONALLY. Without an ingress.enabled switch there is no second value
  path for the mutual-exclusion abort to name, and the Ingress plus its
  unconditional required() on clusterIssuer would have kept rendering in Gateway
  mode - a value demanded for nothing, which is issue #114's "Folge 1" and
  README guideline 12. The switch was added, defaulting to true, so the render is
  unchanged.

  paperless-ngx PAPERLESS_URL had no required() of its own: it relied on the
  Ingress template's, which stops firing the moment the Ingress is switchable.
  With httpRoute.hostnames set and ingress.domain empty it would have rendered
  "https://" and refused every login POST as a CSRF failure. It now carries its
  own required(), naming what the value is for.

  calibre-web-automated claimed, in values.yaml and in its schema, that
  ingress.domain is read nowhere but in the Ingress template. The HTTPRoute reads
  it, so the claim now holds only while both modes are off. Corrected rather than
  left standing - the same correction garage needed in group 1.

freesailarr is where the Gateway API is LESS machinery than what it replaces,
not a translation of it. rewrite-target applies per Ingress OBJECT, so
qBittorrent (no base path, prefix must be stripped) needed a second Ingress on
the shared host, which then had to repeat the first object's TLS secret name,
omit the cert-manager annotation conditionally so only one Certificate is
requested, and match an ImplementationSpecific regex path for the rewrite's
capture group. A URLRewrite filter applies per RULE: one route, one rule per
app, the filter on qBittorrent's rule, a plain PathPrefix. All four crutches
gone. It is also the only chart without httpRoute.hostnames - it has no
ingress.domain either, and a chart-global hostname list could not say which of
the ten apps it belonged to, so the hostnames stay in ingress.host and
<app>.ingress.host.

CI: one render overlay per chart under ci/httproute/, so the assertion is not
vacuum-green - ci/run-httproute-match-test.sh goes from 20 held assertions over
10 charts to 36 over 15. freesailarr's overlay moves bazarr onto a host of its
own, so the shared-host route AND the per-app route are both rendered; without
that the per-app branch would be exercised by nothing. The install-test fixtures
stay in Ingress mode: the install runs one configuration per chart, cyberchef
already pays that price against the real Gateway-API CRDs, and for paperless-ngx
that fixture is the only install of the valkey-subchart path anywhere.

README also carries a stale figure fixed here: the HTTPRoute test was still
documented at the pilot's 4 assertions over 2 charts, although group 1 had taken
it to 20 over 10.

Not proven, by construction: that traffic flows. No Gateway controller runs in
CI. Not run locally either: k3d, Docker, Trivy. The Gateway branch of NOTES.txt
is EXECUTED by the render test (a template error in it fails the job, verified)
but its text is printed by no pipeline stage - helm template does not emit
notes, and the install-test installs in Ingress mode.

Part of #114

outline/templates/NOTES.txt

@@ -1,21 +1,70 @@
 {{- $replicas := include "outline.replicas" (dict "scaleDown" .Values.scaleDown "replicas" .Values.outline.replicas) -}}
 {{- $startup := fromYaml (include "outline.startupProbe" .Values.outline.startupProbe) -}}
 {{- $upload := .Values.outline.maxUploadSize | toString -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list .Values.ingress.domain -}}
+{{- end -}}
 Outline {{ .Chart.AppVersion }} — release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.
 
 {{- if .Values.ingress.enabled }}
 
-ACCESS
+ACCESS — INGRESS MODE (ingress.enabled: true, httpRoute.enabled: false)
   https://{{ .Values.ingress.domain }}
 
   The certificate is requested by cert-manager through the "{{ .Values.ingress.clusterIssuer }}"
   cluster issuer. Until it has been issued the browser shows a warning; follow it with
 
     kubectl -n {{ .Release.Namespace }} get certificate tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress
+{{- else if $httpRoute.enabled }}
+
+ACCESS — GATEWAY MODE (httpRoute.enabled: true, ingress.enabled: false)
+{{- range $hostnames }}
+  https://{{ . }}
+{{- end }}
+
+  This release renders an HTTPRoute ({{ .Release.Name }}-{{ .Chart.Name }}-httproute) and NOTHING
+  else of the routing path — no Gateway, no class, no Certificate. Three things
+  therefore belong to the cluster and not to this chart, and if any is missing
+  the address above does not answer:
+
+    1. The Gateway-API CRDs. Without them this install would have failed.
+    2. The Gateway named in httpRoute.parentRefs
+{{- range $httpRoute.parentRefs }}
+         {{ .name }}{{ if .namespace }} in namespace {{ .namespace }}{{ end }}{{ if .sectionName }}, listener {{ .sectionName }}{{ end }}
+{{- end }}
+       must exist AND its listener must allow routes from this namespace
+       ({{ .Release.Namespace }}) in allowedRoutes. A rejected attachment shows
+       up only in the route's status:
+
+         kubectl -n {{ .Release.Namespace }} get httproute {{ .Release.Name }}-{{ .Chart.Name }}-httproute -o yaml
+
+       Read status.parents[].conditions — "Accepted: True" and
+       "ResolvedRefs: True" is a working attachment. An empty status means no
+       controller has looked at the route at all.
+    3. The TLS certificate for the hostname, on the Gateway's listener.
+       ingress.clusterIssuer is NOT used in this mode and is not required: the
+       chart renders no Certificate, so there is no
+       tls-{{ .Release.Name }}-{{ .Chart.Name }}-ingress secret and nothing for cert-manager to do.
+
+  ingress.domain is still required in this mode and is {{ .Values.ingress.domain }}: it becomes
+  Outline's URL variable, which builds every generated link, every share URL
+  and the OIDC redirect URI. The route does not replace it. If you set
+  httpRoute.hostnames to a name ingress.domain does not carry, the route
+  publishes one host while the app hands out links for another — and an OIDC
+  login then fails on a redirect_uri the provider does not know. Set both
+  together.
+
+  ingress.annotations is inert in this mode: the Gateway API has no annotation
+  channel. WebSockets need none — Outline's realtime editing upgrades on the
+  same port and a plain HTTPRoute passes that through, exactly as the Ingress
+  did without an annotation.
 {{- else }}
 
-ACCESS — NO INGRESS
-  ingress.enabled is false, so this release has no Ingress and no certificate.
+ACCESS — NEITHER INGRESS NOR HTTPROUTE
+  ingress.enabled and httpRoute.enabled are both false, so this release is not
+  published: no Ingress, no HTTPRoute and no certificate.
   ingress.domain is still required: it becomes Outline's URL variable, which
   builds every generated link, every share URL and the OIDC redirect URI.
   Reach the instance inside the cluster with
@@ -31,7 +80,9 @@ SCALED TO ZERO
   {{ if .Values.scaleDown }}scaleDown: true{{ else }}outline.replicas: 0{{ end }} — the StatefulSet runs with replicas: 0, so the endpoint
   above does not answer until you set it back and upgrade again. PVC, Secrets,
   Service{{ if .Values.ingress.enabled }} and Ingress stay in place, so neither the uploads nor the
-  certificate are touched.{{ else }} and the uploads on the PVC stay in place.{{ end }}
+  certificate are touched.{{ else if $httpRoute.enabled }} and HTTPRoute stay in place, so the uploads are not touched — the
+  route then resolves to a Service with no endpoints and the Gateway answers
+  its own error.{{ else }} and the uploads on the PVC stay in place.{{ end }}
 {{ end }}
 WHAT THE THREE 1PASSWORD ITEMS MUST CONTAIN
   The chart creates OnePasswordItem CRs; the operator turns each into a
@@ -135,13 +186,35 @@ TWO UPLOAD CEILINGS, THE SMALLER ONE WINS
   ingress controller's 413 page instead of a message from the app. With the
   chart defaults the Ingress is the tighter of the two by a factor of ten.
   Raise both, or neither.
+{{- else if $httpRoute.enabled }}
+
+YOUR UPLOAD CEILING IS NOT ingress.maxUploadFileSize ANY MORE — IT IS THE GATEWAY'S
+  outline.maxUploadSize        {{ $upload }}{{ if regexMatch "^[0-9]+$" $upload }} bytes (~{{ div (int64 $upload) 1048576 }} MiB){{ else }} — Outline reads this as a plain byte count{{ end }}
+  ingress.maxUploadFileSize    {{ .Values.ingress.maxUploadFileSize }} — NOT ENFORCED in this mode
+
+  The chart renders ingress.maxUploadFileSize into
+  nginx.ingress.kubernetes.io/proxy-body-size, and the Gateway API has NO
+  counterpart — it knows no body size at all, that is implementation-specific
+  policy — so this chart deliberately renders no policy object, which would
+  bind it to one implementation. The ceiling that actually bites is therefore
+  the smaller of outline.maxUploadSize and WHATEVER THE GATEWAY ENFORCES, and
+  the chart can only name the first of those two. Set the limit at the Gateway
+  or through its implementation's own policy object, next to the Gateway and
+  not here.
+
+  Read that next to Gitea #12, which is about exactly this pair: with the chart
+  defaults the two documented numbers are a factor of ten apart. In this mode
+  the ingress half is gone, so neither of them is necessarily the one that
+  decides — which moves that defect rather than fixing it. Check the Gateway's
+  own limit before trusting either number.
 {{- else }}
 
 UPLOAD CEILING
   outline.maxUploadSize   {{ $upload }}{{ if regexMatch "^[0-9]+$" $upload }} bytes (~{{ div (int64 $upload) 1048576 }} MiB){{ else }} — Outline reads this as a plain byte count{{ end }}
 
-  Without an Ingress this is the only limit the chart sets — whatever proxy
-  you put in front adds its own, usually much smaller, body-size cap.
+  With neither routing mode on, this is the only limit the chart sets —
+  whatever proxy you put in front adds its own, usually much smaller,
+  body-size cap. ingress.maxUploadFileSize ({{ .Values.ingress.maxUploadFileSize }}) is rendered nowhere.
 {{- end }}
 
 THE CHART CONFIGURES NO MAIL

outline/templates/outline.httproute.yaml

@@ -0,0 +1,110 @@
+{{/*
+The Gateway-API alternative to outline.ingress.yaml (Gitea #114). Form and
+reasoning: template-chart/templates/xxx.httproute.yaml and README, "Ingress and
+Gateway API".
+
+Only an HTTPRoute with parentRefs. No Gateway, no gatewayClassName, no
+Certificate, and no implementation-specific policy object - that subset looks
+identical on nginx-gateway-fabric, Cilium, Envoy Gateway and Istio, which is
+the whole reason the cluster's implementation can be swapped without touching
+this chart. Class and certificate therefore belong to the PLATFORM, on the
+Gateway and its listeners.
+
+ingress.clusterIssuer is meaningless here - this chart renders no Certificate
+in this mode - and it is not demanded either: its only required() sits inside
+outline.ingress.yaml, behind ingress.enabled.
+
+ingress.domain IS STILL REQUIRED, AND NOT BECAUSE OF THIS FILE
+
+Checked for this chart rather than copied: ingress.domain is read once more
+outside both routing templates, in outline.sfs.yaml, where it builds Outline's
+URL variable and carries its own required(). URL is what every generated link,
+every share URL and the OIDC redirect URI are built from, so domain is
+mandatory in EVERY mode of this chart - the fallback below is never its only
+reader. Setting httpRoute.hostnames to a name ingress.domain does not carry
+therefore publishes the route under one name while the app hands out links
+under another, and an OIDC login fails on a redirect_uri the provider does not
+know. Set both together.
+
+THE UPLOAD LIMIT, AND WHY THIS MODE MOVES Gitea #12 INSTEAD OF FIXING IT
+
+ingress.maxUploadFileSize is rendered into proxy-body-size and
+nginx.org/client-max-body-size by the Ingress template. The Gateway API has NO
+counterpart: a request-body limit is implementation-specific policy and lives
+in an implementation's own object (ClientSettingsPolicy, ClientTrafficPolicy
+and their equivalents), which this chart deliberately does not render. So the
+value is DOCUMENTED as unenforced in NOTES.txt rather than rebuilt.
+
+That matters more here than anywhere else in this sweep, because this chart is
+the one with the open defect: outline.maxUploadSize is 250 MB by default while
+ingress.maxUploadFileSize is 25m - a factor of ten, and the smaller number
+wins (Gitea #12). In Gateway mode the ingress half of that pair DISAPPEARS, so
+the effective ceiling becomes the Gateway's, which is neither of the two values
+the chart documents. That CHANGES the situation of #12; it does not resolve it,
+and this file deliberately does not try to: the chart would have to render a
+policy object to do so, which is exactly the portability the sweep is buying.
+The honest statement is in NOTES.txt for this mode: whichever of
+outline.maxUploadSize and the Gateway's limit is smaller decides, and the chart
+can only name one of them.
+*/}}
+{{- /*
+Null-safe like every other block this chart dereferences (#99): an override
+written without children - "httpRoute:" with the keys below it deleted - is
+YAML null, and `.Values.httpRoute.enabled` would abort the render with a nil
+pointer. An empty block means "chart defaults apply", and all three defaults
+are empty or false, so the whole block collapses to "no HTTPRoute".
+*/ -}}
+{{- $httpRoute := .Values.httpRoute | default dict -}}
+{{- if and $httpRoute.enabled .Values.ingress.enabled -}}
+{{- fail "ingress.enabled and httpRoute.enabled are both true - set exactly one of them. The Ingress and the HTTPRoute would publish the same Service under the same hostname over two different data paths, which is already a conflict at DNS level: one name, two addresses, and which one a client reaches is luck. A migration runs over a SECOND hostname (set httpRoute.hostnames explicitly while the Ingress keeps ingress.domain), never over parallel operation of both." -}}
+{{- end -}}
+{{- if $httpRoute.enabled -}}
+{{- $parentRefs := $httpRoute.parentRefs | default list -}}
+{{- if not $parentRefs -}}
+{{- fail "httpRoute.enabled is true but httpRoute.parentRefs is empty - an HTTPRoute without a parent attaches to no Gateway. It is created, it is schema-valid, and it routes NOTHING, with no event and no condition that says so; the only symptom is a hostname that does not answer. Name the cluster's Gateway, e.g. httpRoute.parentRefs: [{name: public, namespace: gateway}]." -}}
+{{- end -}}
+{{- /*
+One source of truth for the hostname: an empty httpRoute.hostnames means
+[ingress.domain], so the two cannot drift apart. ingress.domain is read here
+even though no Ingress is rendered in this mode - the value names the public
+hostname of this release, which both modes need; it is not an Ingress switch.
+A hostname set explicitly here does NOT move Outline's URL variable with it:
+that keeps following ingress.domain, so the two have to be set together or the
+app publishes links nobody can follow.
+*/ -}}
+{{- $hostnames := $httpRoute.hostnames | default list -}}
+{{- if not $hostnames -}}
+{{- $hostnames = list (required "A Domain/Host must be provided: set ingress.domain (used as the HTTPRoute's single hostname when httpRoute.hostnames is empty) or set httpRoute.hostnames explicitly" .Values.ingress.domain) -}}
+{{- end -}}
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: {{ .Release.Name }}-{{ .Chart.Name }}-httproute
+spec:
+  parentRefs:
+    {{- toYaml $parentRefs | nindent 4 }}
+  hostnames:
+    {{- toYaml $hostnames | nindent 4 }}
+  rules:
+    # The Ingress counterpart is `path: / , pathType: Prefix` on the one
+    # backend Service - Outline serves its UI, its API and its collaborative
+    # WebSocket from one process on one port, so a single path covers all
+    # three. The port is the Service's port NUMBER and not its name ("http"):
+    # backendRefs takes a PortNumber, so unlike the Ingress this reference
+    # cannot be made by name and the 80 below has to track
+    # outline.service.yaml by hand.
+    # ci/run-httproute-match-test.sh is what holds that pair - it fails when a
+    # backendRef names a Service, or a port, the same render does not create.
+    #
+    # WEBSOCKETS: nothing to configure, in either mode. Outline's realtime
+    # editing runs over a WebSocket upgrade on the same port, and the Gateway
+    # API passes an upgrade through on a plain HTTPRoute - there is no
+    # annotation involved in Ingress mode either.
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /
+      backendRefs:
+        - name: {{ .Release.Name }}-{{ .Chart.Name }}-service
+          port: 80
+{{- end }}