Architecture

Request Flow

Browser
  │
  ▼ Cloudflare (Access JWT + DNS)
  │
  ▼ Web Gateway Lambda (per-cogent, Function URL, no VPC)
  │
  ▼ Validate Cloudflare Access JWT
  │
  ├─── Static: /*
  │    ▼ map URL → web/{path}
  │    ▼ lookup: web/{path} → web/{path}/index.html → 404
  │    ▼ read from Postgres via RDS Data API
  │    ▼ return content + Cache-Control: no-store
  │
  └─── Dynamic: /api/*
       ▼ append to io:web:request channel
       ▼ auto-delivery created, handler marked RUNNABLE
       ▼ push to SQS ingress (FIFO, with MessageGroupId)
       ▼ ingress Lambda → executor dispatches handler
       ▼ handler calls web.respond()
       ▼ writes to cogos_web_response table
       ▼ gateway polls table (exponential backoff, 30s timeout)
       ▼ return HTTP response (or 504 on timeout, 502 on error)

Three Layers

Layer 1: AWS Infrastructure (cogtainer CDK stack)

Gateway Lambda

Python 3.12, 512 MB, 60s timeout, Function URL, no VPC (RDS Data API). The only new AWS resource.

Cloudflare DNS

Points subdomain at Function URL. Access policy already exists.

IAM Role

RDS Data API (file store + channels + web_response table), SQS ingress push.

Response Table

cogos_web_response — lightweight request_id → response mapping. Rows TTL'd after 5 min.

Layer 2: CogOS Runtime (image boot)

web capability

publish(), unpublish(), respond(), list() — registered in init/capabilities.py like discord.

io:web:request

System channel for inbound HTTP requests. Created at boot like io:discord:dm.

Every cogent gets these. A cogent that doesn't use web pays nothing.

Layer 3: Cogent Application (optional)

Web cog

Defined in apps/website/init/cog.py. Daemon subscribed via handlers=["io:web:request"].

Handler prompt

Coglet's main.md — reads request, does work, calls web.respond(). Route logic lives here.

Published files

Any process with web capability calls web.publish("path", content). Stored at web/* in file store.

Discord Analogy

      
          Concept
          Discord
          Web
        
          IO Bridge
          Discord Bridge (Fargate)
          Web Gateway Lambda
        
          Inbound Channel
          io:discord:dm
          io:web:request
        
          Capability
          discord.send_message()
          web.respond() / web.publish()
        
          Response mechanism
          Fire-and-forget (post to Discord)
          cogos_web_response table (sync)
        
          Dispatch
          append → delivery → ingress → executor
          append → delivery → ingress → executor
        
          Handler
          discord cog handler coglet
          web cog handler coglet

Concept	Discord	Web
IO Bridge	Discord Bridge (Fargate)	Web Gateway Lambda
Inbound Channel	io:discord:dm	io:web:request
Capability	discord.send_message()	web.respond() / web.publish()
Response mechanism	Fire-and-forget (post to Discord)	cogos_web_response table (sync)
Dispatch	append → delivery → ingress → executor	append → delivery → ingress → executor
Handler	discord cog handler coglet	web cog handler coglet

Response Mechanism

cogos_web_response table (not channels)

CREATE TABLE cogos_web_response (
  request_id  UUID PRIMARY KEY,
  status      INTEGER DEFAULT 200,
  headers     JSONB DEFAULT '{}',
  body        TEXT DEFAULT '',
  error       TEXT,
  created_at  TIMESTAMPTZ DEFAULT now()
);

        Gateway polls by request_id (exponential backoff: 100ms, 200ms, 400ms...)

        Handler writes via web.respond() → INSERT into table

        Gateway reads row → returns HTTP → deletes row

        Cleanup: dispatcher tick deletes rows older than 5 min
      

Concurrency (v1)

Serial handler. One daemon process, requests queue behind each other.

If handler is WAITING → first request dispatches it immediately.
If handler is RUNNING → new deliveries queue until it loops back.

Mitigations:

30s gateway timeout → stale requests get 504'd
Handlers should respond fast + spawn child processes for expensive work (202 pattern)
Future: handler process pool for parallelism

v1 Limitations