Skip to content

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.

Source of truth