mirror of
https://github.com/nestriness/nestri.git
synced 2026-09-19 17:25:19 +03:00
51ababc900
Moving the issuer's state into Postgres removed the last thing that tied either app to one hosting provider. What was left was a deployment tool describing resources that no longer existed — so this replaces it with `wrangler`, which is what actually deploys a Worker, and adds a second way to run each app that involves no provider at all. Each app now has a `wrangler.jsonc` with an environment per stage, and a `Dockerfile` beside it. The handler is the same one in both cases; what differs is only where its settings come from. Two of them gained a second spelling so that nothing has to branch on the runtime: Postgres arrives as a pooled binding or as `DATABASE_URL`, and the route to the issuer is a service binding or `AUTH_INTERNAL_URL`. That last one is new, and it is a split the binding was already making without saying so. `AUTH_ISSUER_URL` has to be the issuer's public name, because it is compared literally against every token's `iss` claim — but the public name is often not routable from inside a deployment. So the name and the route are two settings now rather than one that cannot be both. DNS moves out of code and into `docs/dns.md`, which lists every hostname and what it is for. Six records that change roughly never did not need a tool, and the table outlives whatever is answering the names — which is the point, since some of them will stop being Workers. The sandbox hostnames are hyphenated rather than nested for the same reason: a certificate covering `*.nestri.io` covers one label and not two, so `api-sandbox.nestri.io` can become an ordinary origin later without a certificate having to be ordered for it first. Also drops `EMAIL_DEV_LOG` from committed configuration into `.dev.vars`, which `wrangler deploy` cannot upload. Printing a live sign-in code to a log should not be one forgotten override away from production.
58 lines
2.8 KiB
Markdown
58 lines
2.8 KiB
Markdown
# apps/api
|
|
|
|
The public HTTP API for Nestri — a [Hono](https://hono.dev) app. One handler, run either as a
|
|
Cloudflare Worker or as an ordinary HTTP server.
|
|
|
|
## What it does
|
|
|
|
Exposes the JSON API consumed by frontends and other clients. Every route is a thin wrapper that
|
|
validates input, delegates to a domain function in [`@nestri/core`](../../packages/core/README.md),
|
|
and returns `{ data: ... }`. All business logic lives in the core package.
|
|
|
|
Routes:
|
|
|
|
| Prefix | Purpose |
|
|
| ----------------- | ------------------------------------------------------------- |
|
|
| `/` | Health check |
|
|
| `/user` | Current user profile, fingerprints, linked accounts |
|
|
| `/steam` | Link / sync / unlink a Steam account |
|
|
| `/library` | Owned games with playtime |
|
|
| `/games` | Game catalog |
|
|
| `/pairing-code` | Device pairing codes |
|
|
| `/machine` | Host machines |
|
|
| `/access-token` | Short-lived access tokens |
|
|
| `/doc` | Generated OpenAPI spec |
|
|
|
|
## Structure
|
|
|
|
```text
|
|
app/
|
|
index.ts # The handler: middleware, routes, error handler, /doc
|
|
server.ts # The same handler behind a listening socket
|
|
middleware/auth.ts # Bearer JWT + admin shared-secret auth → Actor
|
|
routes/*.ts # Thin route namespaces (UserApi, SteamApi, ...)
|
|
utils/ # ErrorResponses, Result(), validator wrapping
|
|
wrangler.jsonc # Worker configuration, one environment per stage
|
|
Dockerfile # The container, built from the repository root
|
|
test/ # Route tests
|
|
```
|
|
|
|
## Key details
|
|
|
|
- Auth: `Authorization: Bearer <JWT>` verified against `@nestri/auth`; or the `x-nestri-admin-token` header (see `ADMIN_SHARED_SECRET`).
|
|
- Errors: centralized `VisibleError` → typed JSON responses.
|
|
- Settings arrive as bindings or as environment variables, and two of them have one spelling of
|
|
each: Postgres is `HYPERDRIVE` or `DATABASE_URL`, and the route to the issuer is an `AUTH`
|
|
service binding or `AUTH_INTERNAL_URL`. Nothing here branches on which it got.
|
|
- `AUTH_ISSUER_URL` is the issuer's **public** URL and never the internal one, because it is
|
|
compared literally against the `iss` claim on every token.
|
|
|
|
## Running
|
|
|
|
```sh
|
|
bun run dev # under the Workers runtime, on :3000
|
|
bun run serve # as a plain process, on $PORT (default 3000)
|
|
```
|
|
|
|
Needs a Postgres database and a reachable issuer. Full list and deployment steps:
|
|
[`docs/deploy.md`](../../docs/deploy.md). |