url4-cloud on PULSE
url4-cloud is ScreamingFace's public execution control plane. It mints single-run capability tickets, accepts REST execution requests, streams lifecycle events over WebSocket, and creates one ephemeral Kubernetes Runner Job per run. ScreamingFace owns the application and chart; PULSE owns its public route and runtime boundary.
Dependencies and ports
flowchart LR
E[Envoy Gateway] -->|REST and WebSocket<br/>TCP 9108| U[url4-cloud]
G[Gatus] -->|healthz<br/>TCP 9108| U
U -->|Kubernetes API<br/>exact namespace RBAC| K[Runner Job]
U <--> |JetStream<br/>TCP 4222| N[NATS]
K <--> |JetStream<br/>TCP 4222| N
K -->|OpenAI-shape API<br/>TCP 9105| A[aigateway]
| Surface | Purpose | Important boundary |
|---|---|---|
POST /token |
Mint a topic-scoped capability ticket | Ticket lifetime is 60 seconds; it is not a Cloudflare credential |
GET /?q=... |
Start a run; synchronous by default or asynchronous with Prefer |
Requires a valid capability and an attached subscriber |
DELETE / |
Stop the authorized run and remove its event stream | Topic must match the capability |
GET /v1/models |
Proxy the caller-scoped aigateway model catalog | Identity and optional X-Profile are forwarded; result is private-cache scoped |
GET /healthz |
Process health for the continuous check | Does not prove NATS, Runner, or aigateway |
GET /readyz |
Application readiness | Still not provider-completion proof |
GET /ws?ticket=... |
Ticketed lifecycle stream | Public route timeout is explicitly disabled |
Execution protocol
sequenceDiagram
participant C as Client
participant U as url4-cloud
participant N as JetStream
participant R as Runner
participant A as aigateway
C->>U: POST /token
U-->>C: short-lived capability
C->>U: WebSocket /ws?ticket=...
U-->>C: connection accepted
C->>U: ai.url4.attach {from_sequence: 1}
C->>U: GET /?q=... with capability
U->>R: create namespaced Job
U-->>C: 202 or bounded synchronous response
R->>N: lifecycle events
R->>A: model request when expression requires it
N-->>U: subscribed events
U-->>C: started ... result ... terminated
Connection and attachment are separate states. Opening the WebSocket registers
the topic for the current subscriber gate, but event delivery starts only
after a valid ai.url4.attach. This mismatch is a known defect: the REST
precondition can pass before protocol attach. Keep one url4-cloud replica until
the gate is based on successful attach, auto-attach is adopted, or subscriber
state becomes shared.
from_sequence is 1-based and inclusive. Omitting it replays from the start of
the retained stream. Re-attaching replaces the existing stream subscription on
that connection.
Runner and state model
The server is a stateless control plane around Kubernetes Jobs and JetStream. Its ServiceAccount token is intentionally mounted because it must create, inspect, watch, and delete Jobs and inspect their Pods and logs. The platform-owned Role grants only those namespaced actions and no Secret reads.
Each Runner uses the same pinned image as the server and receives configuration through references, not literal credential values in the Job. Runner stdout is for diagnosis; a successful application result is an event in JetStream. A Job that exits cleanly without a terminal result is not a successful run.
NATS provides per-topic lifecycle retention and replay. Completed Job names also act as the single-use replay guard while a capability remains valid.
Identity and aigateway
Envoy supplies the verified user identity to url4-cloud. The request may carry
an X-Profile selector, which url4-cloud passes to the Runner and aigateway.
url4-cloud does not hold a provider credential and does not decide whether the
profile is authorized.
The model catalog is cached per derived caller identity and profile. It returns aigateway's model identifiers verbatim. Execution expressions must use the provider-prefixed canonical model identifier returned by that catalog.
Readiness versus functional proof
| Signal | Proves | Does not prove |
|---|---|---|
/healthz is 200 |
Process, Service, and allowed probe reachability | JetStream, Job creation, WebSocket attach, aigateway |
| Argo is healthy | Desired Kubernetes resources reconciled | Correct protocol behavior |
| Local expression lifecycle | Capability, attach, Job, and JetStream paths | aigateway or provider execution |
| Provider-backed lifecycle | Full execution through an approved profile | Only valid when canonical model, profile, and spend controls are recorded |
Common failure signatures
| Symptom | First contract to inspect |
|---|---|
| 401/403 before the app | Cloudflare Access identity and client User-Agent |
| WebSocket closes with policy violation | Missing, expired, or invalid ticket |
| REST returns 428 | Socket was not connected to the same topic; protocol attach may also be missing |
| Connected socket receives no events | ai.url4.attach was not sent or its frame was invalid |
| Job never appears | url4-cloud ServiceAccount token, Role/RoleBinding, or API-server egress |
| Job exists but no lifecycle arrives | Runner/NATS connectivity, Runner configuration, and terminal event publishing |
| Local expression succeeds but model call fails | Expected: local execution does not exercise aigateway; inspect model/profile contract |
| aigateway rejects the model | Use the provider-prefixed identifier from /v1/models |
| New token stops working after delay | Mint a fresh ticket; the capability window is 60 seconds |
Programmatic public clients must send a real User-Agent. Cloudflare bot
protection rejected the default Python-urllib User-Agent during acceptance.
Change and rollback boundary
A url4-cloud bump must move the chart commit and image tag together. Re-review the Service name, labels, port, Runner label, RBAC request, NATS contract, Secret keys, and probe paths. If any changes, update the platform companion resources in the same infrastructure change.
Rollback means repinning a previously accepted chart/image pair and verifying the full public lifecycle. The retired trial is not a rollback target.