| 1 | --- |
| 2 | title: How a request is served |
| 3 | description: What happens between a request reaching g1t.sh or api.g1t.sh and its answer leaving, step by step, with the deadlines, caches, rate limits and timings along the way. |
| 4 | --- |
| 5 | |
| 6 | import Aside from '../../../components/Aside.astro'; |
| 7 | import Diagram from '../../../components/Diagram.astro'; |
| 8 | |
| 9 | Two Workers answer almost everything you send g1t: the site, `apps/web` |
| 10 | on `g1t.sh`, and the API, `apps/api` on `api.g1t.sh` and `mcp.g1t.sh`. |
| 11 | Neither keeps data. Each works out who is asking, then calls the services |
| 12 | that own the answer. |
| 13 | |
| 14 | ## The site |
| 15 | |
| 16 | `apps/web/workers/app.ts` is the site's entry point. It sorts each request |
| 17 | before any page code runs: |
| 18 | |
| 19 | 1. A request for `g1tusercontent.com` goes to `serveUsercontent`, which |
| 20 | never reads or sets the session cookie. |
| 21 | 2. `go get` lookups get their meta page. |
| 22 | 3. **git over HTTPS** (paths ending in `info/refs`, `git-upload-pack` or |
| 23 | `git-receive-pack`) passes the git rate limits, then goes to `repos` |
| 24 | whole, through `env.REPOS.fetch`. The site never parses git |
| 25 | ([Git](/architecture/git/)). |
| 26 | 4. **Package registries** (`/v2/`, `/-/npm/`, `/-/cargo/` and the others) |
| 27 | go to `packages` whole. A 404 is tried once more under the workspace's |
| 28 | current name, so a renamed workspace's old URLs keep working. |
| 29 | 5. Everything else passes the page rate limit and reaches React Router. |
| 30 | |
| 31 | ### A page |
| 32 | |
| 33 | <Diagram name="page-request" /> |
| 34 | |
| 35 | The root route's middleware, `viewerMiddleware` in |
| 36 | `apps/web/app/lib/session.server.ts`, resolves the viewer once (steps 2 |
| 37 | and 3). The `g1t_session` cookie is 64 hex characters, `HttpOnly`, |
| 38 | `Secure` and `SameSite=Lax`, and lasts 30 days; `identity` stores only its |
| 39 | SHA-256. A request can send `Authorization: Bearer` with an access token |
| 40 | that has the **website** permission instead of the cookie. The same |
| 41 | middleware enforces the email confirmation, workspace and Code access |
| 42 | gates. |
| 43 | |
| 44 | Loaders then call their services together (steps 4 to 7). They use the |
| 45 | typed clients in `@g1t/contracts`, built in `app/lib/services.server.ts`, |
| 46 | and pass the viewer in each call's arguments. Nothing waits on a call it |
| 47 | does not need. |
| 48 | |
| 49 | ### Deadlines |
| 50 | |
| 51 | Each binding is wrapped by `instrumented()` in `app/lib/perf.server.ts`, |
| 52 | which gives every call a deadline (`app/lib/deadline.ts`). A call that |
| 53 | outlives it is aborted and throws `DeadlineExceeded`, so one slow service |
| 54 | cannot hold a page forever. |
| 55 | |
| 56 | | Call | Deadline | |
| 57 | | --- | --- | |
| 58 | | A read | 15 s | |
| 59 | | A write, or a read named in `SLOW_READS` | 60 s | |
| 60 | | A long job, named in `LONG_CALLS` | 600 s | |
| 61 | |
| 62 | ### Reading your own writes |
| 63 | |
| 64 | D1 has read replicas. The site uses D1's Sessions API with the services |
| 65 | that support it (`identity`, `repos`, `work`, `search`, `billing`, |
| 66 | `projects`, `deployments`) by sending an `x-d1-bookmark` header on each |
| 67 | call. The latest bookmark is kept in the `g1t_d1` cookie for 5 minutes, |
| 68 | and for 30 seconds after a write, reads go to the primary. You never see a |
| 69 | page older than a change you just made. The service side is |
| 70 | `crates/kit/src/d1.rs`; TypeScript services use |
| 71 | `packages/contracts/src/d1.ts`. |
| 72 | |
| 73 | ### The public page cache |
| 74 | |
| 75 | A signed-out `GET` with no cookie and no `Authorization` header, for a |
| 76 | public page, can be answered from the colo's cache. It is fresh for 30 |
| 77 | seconds, then served stale while it refreshes in the background, for up |
| 78 | to 5 minutes. Before a cached repository page is served, the site asks |
| 79 | `repos` whether the repository is still public, so making it private |
| 80 | takes effect at once. |
| 81 | |
| 82 | ### Server-Timing |
| 83 | |
| 84 | Every page carries a `Server-Timing` header: the total, each loader, each |
| 85 | service's calls and time, and the database time each service reports |
| 86 | about itself (`svc`, `db` and `rpc`, from `Served` in |
| 87 | `crates/kit/src/d1.rs`). A cached page says |
| 88 | `cache;desc="hit, Ns old"`. Open your browser's network panel on any page |
| 89 | to see where its time went. |
| 90 | |
| 91 | <Aside title="Where it runs"> |
| 92 | Every Worker runs with placement off, in the data centre nearest the |
| 93 | visitor. `scripts/perf/placement-probe.mjs` measures the alternative, |
| 94 | and CONTRIBUTING.md's **Speed** section has the rules this design |
| 95 | follows: start calls together, add no round trips, and never wake a |
| 96 | Durable Object for a read D1 can answer. |
| 97 | </Aside> |
| 98 | |
| 99 | ## The API and MCP |
| 100 | |
| 101 | `apps/api` serves both `api.g1t.sh` and `mcp.g1t.sh` from one Worker; a |
| 102 | host starting `mcp.` is the MCP server. It sorts each request in this |
| 103 | order (`apps/api/src/lib.rs`): |
| 104 | |
| 105 | 1. OTLP at `/otlp/v1/*` goes to `telemetry` as it is. |
| 106 | 2. Requests that bring their own credentials are handled before any g1t |
| 107 | token is read: the Stripe webhook, inbound integration hooks at |
| 108 | `/hooks/<id>`, deployment build jobs, the Actions toolkit and OIDC |
| 109 | issuer, a job's artifacts, cache and brokered requests, and the runner |
| 110 | protocol at `/runners/*`. |
| 111 | 3. Rate limits. |
| 112 | 4. The token. |
| 113 | 5. OAuth. |
| 114 | 6. MCP, when the host says so. |
| 115 | 7. The REST routes. |
| 116 | |
| 117 | <Diagram name="api-request" /> |
| 118 | |
| 119 | A token is sent as `Authorization: Bearer g1t_…` (or `token g1t_…`) and |
| 120 | resolved by `identity` (step 3). A wrong or expired one gets a 401 with a |
| 121 | `www-authenticate` header that points at the OAuth metadata, as RFC 9728 |
| 122 | describes, so an MCP client can start signing in by itself. |
| 123 | |
| 124 | ### Scopes |
| 125 | |
| 126 | Scopes are written `resource:level`, and `admin` includes `write`, which |
| 127 | includes `read`. They are defined in `crates/contracts/src/scopes.rs`, and |
| 128 | `packages/contracts/src/scopes.ts` mirrors them. The token's scopes decide |
| 129 | which operations it may call (step 5), and the MCP server lists only the |
| 130 | tools those scopes allow. A workflow job's token carries the job's own, |
| 131 | narrower scope. |
| 132 | |
| 133 | ### One table for every operation |
| 134 | |
| 135 | `apps/api/src/operations.rs` lists every operation once. The REST routes, |
| 136 | the MCP tools and the OpenAPI document at |
| 137 | [`/openapi.json`](https://api.g1t.sh/openapi.json) are all generated from |
| 138 | it; an operation without a description does not compile. The docs' |
| 139 | [API reference](/reference/api/) is built from that document, and the |
| 140 | CLI's command table from the reference, so the four cannot disagree. |
| 141 | |
| 142 | ### snake_case at the edge |
| 143 | |
| 144 | Inside g1t, contracts are camelCase. The API's `reply()` turns every |
| 145 | answer to snake_case on the way out (`g1t_kit::wire::snake_case`), leaving |
| 146 | user-named keys such as inputs, env, secrets and headers as they were |
| 147 | written. Errors keep one shape, `{"error": {"code", "message"}}`, with the |
| 148 | status that the failure's code maps to. |
| 149 | |
| 150 | ### OAuth 2.1 |
| 151 | |
| 152 | The API is the OAuth issuer. It supports authorization code with PKCE for |
| 153 | public clients only, with no client secrets, and dynamic registration at |
| 154 | `POST /oauth/register`, whose client id encodes the client's name and |
| 155 | redirect addresses. The person approves on the site, at |
| 156 | `g1t.sh/oauth/authorize`; the token endpoint, `POST /oauth/token`, asks |
| 157 | `identity` to exchange and refresh. Refresh tokens rotate. |
| 158 | |
| 159 | ### MCP |
| 160 | |
| 161 | The MCP server speaks streamable HTTP with no session state: each `POST` |
| 162 | gets one JSON-RPC answer. It supports protocol versions 2025-06-18, |
| 163 | 2025-03-26 and 2024-11-05. Its tools are resources with an `action`, as |
| 164 | [MCP tools](/reference/mcp/) lists. |
| 165 | |
| 166 | ## Rate limits |
| 167 | |
| 168 | Every limit is a Workers rate-limit binding, and |
| 169 | `packages/contracts/src/rate-limits.ts` is the table of record: a test |
| 170 | checks every `wrangler.jsonc` against it. |
| 171 | |
| 172 | | Where | Limit | Counted by | |
| 173 | | --- | --- | --- | |
| 174 | | The API, without a token | 60 a minute | The client's address | |
| 175 | | The API, with a token | 1,000 a minute | The token, hashed | |
| 176 | | REST and MCP | Counted separately | | |
| 177 | | Sandbox and runner reports | Not counted | | |
| 178 | |
| 179 | When the limiter itself cannot answer, the request goes through: the |
| 180 | limits fail open. The [rate limits page](/reference/rate-limits/) lists |
| 181 | every limit you can hit. |