omnigateway 0.4.13 → 0.5.1

package/README.md

@@ -402,6 +402,53 @@ supervisor; use `omni restart` from a terminal there. Shutdown is offered in
 every shape. In a container it is a one-way door: bring the process back from
 the host.
 
+### Behind a reverse proxy
+
+Set `OMNI_BASE_URL` to the public HTTPS origin, or OAuth callbacks come back to
+the wrong host.
+
+Beyond that, two things travel badly through a proxy, and both are streams.
+Client responses on `/v1/*` are server-sent events, and the console keeps one
+WebSocket open on `/api/stream`. Neither is optional: buffer the first and every
+token of an agent's reply arrives at once at the end, and drop the second and
+the console silently falls back to polling.
+
+Caddy and Cloudflare pass WebSockets and unbuffered responses by default and
+need nothing. nginx needs telling:
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:9000;
+    proxy_http_version 1.1;
+
+    # Without these two the Upgrade handshake never reaches the gateway and the
+    # console shows LIVE·POLL instead of LIVE·PUSH. It keeps working — the
+    # fallback exists for exactly this — but you paid for a socket you are not
+    # getting.
+    proxy_set_header Upgrade    $http_upgrade;
+    proxy_set_header Connection "upgrade";
+
+    proxy_set_header Host              $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    # The socket's heartbeat is 20s and it gives up on a missed pong at 60s.
+    # A read timeout below that closes a healthy connection from the outside,
+    # and the console reconnects in a loop that looks like an unstable gateway.
+    proxy_read_timeout 300s;
+
+    # SSE must not be buffered. The gateway already sends
+    # `x-accel-buffering: no` on streaming responses, which nginx honours on its
+    # own, so this line is belt and braces for a proxy chain where something
+    # else strips that header before nginx sees it.
+    proxy_buffering off;
+}
+```
+
+The gateway sends downstream `: keepalive` comments on streaming responses
+because provider heartbeats are decoded away, so an idle stream still looks
+alive to whatever sits in between. Keep any idle timeout in the proxy above
+your longest expected request.
+
 ## Configuration
 
 Configuration is environment variables, read from the installation's `.env`:
@@ -417,7 +464,6 @@ Configuration is environment variables, read from the installation's `.env`:
 | `OMNI_LOG_LEVEL` | No | `info` | Stdout threshold: `debug`, `info`, `warn`, or `error` |
 | `OMNI_LOG_FILE` | No | the systemd journal, when there is one | Where stdout was already redirected, so the Console screen can read it back. Names a file; does not create one |
 | `OMNI_BODY_LOGGING_ALLOWED` | No | unset | Permits request/response body capture on this installation. Read at boot. Capture also needs the runtime setting; see [Recording bodies](#recording-bodies) |
-| `OMNI_EXPOSE_CLAUDE_CODE_ALIASES` | No | off | Advertises the reserved `claude/*` aliases on `/v1/models`. Read at boot |
 | `OMNI_ROOT` | No | the installation in the current directory, else `~/.config/omnigateway` | Which installation the CLI acts on, when `--root` is not passed |
 | `OMNI_PLUGIN_REGISTRY` | No | the public npm registry | Registry `omni plugin install <name>` resolves through; must be `https://` |
 
@@ -680,6 +726,11 @@ ID       NAME               VERSION  API  SDK     CAPABILITIES
 pokemon  Pokémon Companion  1.0.0    1    ^1.0.0  storage,files,net:outbound,…    ok
 ```
 
+The capabilities a manifest may declare are `storage`, `files`, `net:outbound`,
+`events:request`, `events:limit` and `channels` — the last being namespaced
+topics on the gateway's push socket, which a plugin owns without ever touching a
+connection. Anything a plugin did not declare is absent from what it is handed.
+
 A plugin that would *not* load is listed with the reason rather than hidden,
 because a plugin missing from the console is exactly what you are trying to
 explain. For one plugin's full detail — its entry points and the outbound