diff --git a/docs/backend/accounts.md b/docs/backend/accounts.md index 8d7bd232..69dd3029 100644 --- a/docs/backend/accounts.md +++ b/docs/backend/accounts.md @@ -14,14 +14,26 @@ MistWarp accounts are Rotur accounts. This page covers how a Rotur sign-in becom Only MistWarp's own sign-in token can make app-ID validators (rotur/api#85), so the desktop app, which still uses the old sign-in, and older tokens send the old key. Rotur doesn't check the old key against MistWarp's Rotur App, so for those sign-ins Rotur's suspension, adults-only, parental approval and age settings aren't enforced, and a rotur.dev ban only applies once the five-minute ban sync has brought it in. Old-key validators made by another Rotur App's sign-in are refused. The gap closes once the desktop app uses Sign in with Rotur through a loopback redirect, which needs Rotur to accept any port on `http://127.0.0.1`. -A refusal from Rotur is answered with 403 and its `code`, `error`, and for an app ban its `reason` and `until`. +Rotur answers every validator request with HTTP 200, valid or not, and every "no" comes back as `valid: false` with a `code`. Only `valid: true` signs anyone in. An `invalid_validator` code moves on to the next key, so a validator made for the old key still works. Any other code is a refusal, answered with 403 and its `code`, `error` and `redirectUrl`, and for an app ban its `reason` and `until`. A validator no key accepts answers 401, and so does a non-2xx answer from Rotur. ## Plans Perks follow the person's Rotur plan. mistwarp-api asks the apps API (`GET /v2/apps//users//plan`), which answers whatever their privacy settings. Rotur's public profile hides the plan from anyone who can't see the balance, which covers every account without a date of birth, so it's only read for people the apps API doesn't know. Answers are kept for 5 minutes, and during an outage the last known plan stays. +### Vanity project URLs + +A vanity project URL (`/p/`, resolved by `GET /v1/vanity/:slug`) needs a plan that includes one, which today is Rotur Pro. Once the owner's plan stops including it, the URL stops working but stays reserved for them for 30 days, so resubscribing brings it straight back. After that it's released for anyone to claim. While it's reserved, the owner sees it as `vanityReserved` with `vanityLapsed: true`, so they can keep it or clear it. + +The 30 days only start when Rotur says the plan no longer includes it. While Rotur can't be reached nothing changes: a working URL keeps working, the clock doesn't start, and a lapsed URL isn't released. A loop checks every 15 minutes, so URLs are released on time even if nobody visits them. + ## Bans A MistWarp ban is also a ban from the MistWarp Rotur App (`PUT /v2/apps//bans/`), so Rotur enforces it too: the person's MistWarp tokens stop working and Rotur won't let them sign in to MistWarp. Rotur shows them the ban's reason, and never who made it. Lifting a ban lifts both. Every five minutes MistWarp reads the app's bans. Bans made or lifted on rotur.dev/me/developer reach MistWarp's own list, and any ban or unban Rotur couldn't be told about yet is sent again. A ban lifted in MistWarp is never brought back from Rotur while that's pending. Rotur won't ban the app's owner or managers, classroom students, or accounts it doesn't know, so those bans stay MistWarp-only. Bans whose reason only names a report are sent with a general reason instead. + +## Erasing an account + +Someone deleting their data from Settings, a Rotur erasure request, Rotur saying the account was deleted, left MistWarp or was banned (see [Rotur webhooks](/backend/payments#rotur-webhooks)), and the five-minute `/accounts/deleted_check` reconcile finding a deleted account all erase everything MistWarp holds about the person. That includes their projects and trash, backpack, game data, sessions and community records, and frees everything they counted against their Rotur storage. Reports they filed are kept, with the reporter shown as "Deleted User". + +When a teacher is erased, each class they owned passes to its first remaining co-teacher, who gets a notification. The transfer is recorded in the class's audit log. A class with no co-teacher is deleted with its students. The teacher leaves every class they co-taught, and their school. When that leaves the school without an admin, its first remaining teacher becomes school admin. diff --git a/docs/backend/community.md b/docs/backend/community.md index eb9b22c9..03fe43fd 100644 --- a/docs/backend/community.md +++ b/docs/backend/community.md @@ -44,8 +44,15 @@ GitHub's search quota is 10 requests a minute for an unauthenticated caller and - One search covers the whole org, so a refresh costs two requests rather than one per repository. -- A refresh happens at most once every five minutes. The snapshot is stored, so - a restart reuses it and costs nothing - a crash loop cannot burn the budget. +- A successful refresh happens at most once every five minutes. A failed one is + retried on the next tick, if the recorded quota allows. The snapshot is stored, so + a restart reuses it and costs nothing, and a crash loop cannot burn the budget. +- The loop ticks every minute, more often than the refresh window, so a tick + landing a moment early cannot push the next refresh out by a whole interval. + A tick that finds the snapshot fresh costs nothing. +- A refresh where both searches fail keeps the last good snapshot rather than + overwriting it with nothing. If only one fails, the snapshot is replaced with + what the other found. - Every response's `X-RateLimit-*` headers are recorded, and a refresh is refused when the remaining quota would not cover it, keeping a small reserve for anything else on the same address. diff --git a/docs/backend/configuration.md b/docs/backend/configuration.md index 96c2b9c3..4c622d40 100644 --- a/docs/backend/configuration.md +++ b/docs/backend/configuration.md @@ -13,12 +13,15 @@ The server loads `.env` from the directory it runs in. A value is looked up in t | PORT | 5627 | Listen port | | HISTORY_MIGRATION_WORKERS | 4 | Concurrent background workers used to backfill missing project histories (clamped to 1-8) | | APP_URL | https://api.mistwarp.org | Public URL of this API | +| ROTUR_BASE | https://api.rotur.dev | The public Rotur API, for sign-in, profiles, plans, notifications and the apps API | | ROTUR_APP_KEY | mistwarp | The old validator key, for editors that predate validators keyed to the Rotur App | | COMMERCE_SERVICE_KEY | | Key registered for `mistwarp` in Rotur's `COMMERCE_SERVICE_KEYS`. Only bounty awards and the groups integration still use it | | ROTUR_CLIENT_ID | | The MistWarp Rotur App's client ID (`app_1938b6a87799f862`). With the secret, mistwarp-api calls the apps API as MistWarp | | ROTUR_CLIENT_SECRET | | One of the MistWarp Rotur App's secrets, made with **New secret** on rotur.dev/me/developer | | MISTWARP_ROTUR_USER | | Rotur account that gets MistWarp's share of game product sales. Without it, the MistWarp Rotur App's owner gets it | | ROTUR_WEBHOOK_SECRET | | Signing secret (`whsec_…`) of the MistWarp Rotur App's webhook. Without it `POST /v1/rotur/webhook` answers 503 | +| ROTUR_SERVICE_SECRET | | The Rotur API's own `ROTUR_SERVICE_SECRET`. mistwarp-api uses it to call the Rotur API's storage ledger as the official app `mistwarp`. Without it, storage isn't counted against anyone's Rotur storage (see [Storage limits](/backend/storage#storage-limits)) | +| ROTUR_LOCAL_API_URL | http://127.0.0.1:5602 | The Rotur API on this machine. It must be `http://127.0.0.1:`, `http://localhost:` or `http://[::1]:` with nothing after the port but an optional trailing slash, so the service secret never leaves the machine. Any other value logs a warning at start and turns storage counting off | | R2_ENDPOINT | | https://accountid.r2.cloudflarestorage.com | | R2_BUCKET | mistwarp | R2 bucket name | | R2_ACCESS_KEY_ID | | R2 access key | @@ -42,3 +45,5 @@ The server loads `.env` from the directory it runs in. A value is looked up in t The multiplayer WebSocket runs inside this API process at `/v1/connect`. It uses the same listener, domain, and deployment as the HTTP API. + +mistwarp-api runs on the same machine as the Rotur API. It calls the public Rotur API (`ROTUR_BASE`) like any other app, and the storage ledger directly on `ROTUR_LOCAL_API_URL`. diff --git a/docs/backend/payments.md b/docs/backend/payments.md index 7d1c92ed..f0018fa0 100644 --- a/docs/backend/payments.md +++ b/docs/backend/payments.md @@ -35,10 +35,12 @@ Tests: `python3 -m unittest scripts/test_refund_project_sales.py`, and with a co Set the MistWarp Rotur App's webhook to `https://api.mistwarp.org/v1/rotur/webhook` on rotur.dev/me/developer, with privacy requests on, and put its signing secret in `ROTUR_WEBHOOK_SECRET`. -- `user.deleted`, `user.left` and `user.banned` erase everything MistWarp holds about that person, the same as deleting their data from Settings. +- `user.deleted`, `user.left` and `user.banned` erase everything MistWarp holds about that person, the same as deleting their data from Settings (see [Erasing an account](/backend/accounts#erasing-an-account)). Rotur requires that within 30 days, and MistWarp does it straight away. - A `privacy.request` for `erasure` does the same. One for `access` sends them a MistWarp notification pointing to the download in Settings. - `payment.completed` finishes the purchase it names (see Payments). -Deliveries are checked against `Rotur-Signature` and refused if their timestamp is more than five minutes out. Each is saved to `data/rotur-webhooks.json`, answered, then handled in the background, and a retried delivery is only handled once. Anything not yet handled when the server stops is handled when it starts. +Each delivery carries `Rotur-Webhook-Id`, `Rotur-Webhook-Timestamp` (Unix seconds) and `Rotur-Signature`. The signature is `v1=` and the hex HMAC-SHA256 of `..`, keyed with the whole signing secret, `whsec_` prefix included. A delivery with a bad signature, or a timestamp more than five minutes out, answers 401, and one whose body `id` doesn't match the header answers 400. + +Rotur waits 10 seconds for an answer, and erasing someone can take longer. So each delivery is saved to `data/rotur-webhooks.json`, answered, then handled by a worker, one event at a time. Handled events are kept for at least 7 days, longer than Rotur's 36 minutes of retries, so a retried delivery is only handled once. Anything not yet handled when the server stops is handled when it starts. Rotur only sends these for people who have used MistWarp through Sign in with Rotur, or whose account was made on MistWarp. The five-minute check of `/accounts/deleted_check` stays for everyone else. diff --git a/docs/backend/storage.md b/docs/backend/storage.md index 15037b49..566dccc5 100644 --- a/docs/backend/storage.md +++ b/docs/backend/storage.md @@ -34,9 +34,79 @@ The first editor save uploads a compact MWP archive containing the Git repositor For a delta whose `baseHead` still matches the stored head, the API removes loose Git objects already present in the materialized base before storing the new layer. It retains the delta manifest and refs, verifies the combined archive, and stitches only the new commits and graph nodes ahead of `baseHead` onto the inherited metadata. A final locked head comparison rejects concurrent history changes before project metadata is saved. +### Generated history + +Projects saved before history existed, or uploaded without a history archive, get one generated from their stored snapshot. At every start, `HISTORY_MIGRATION_WORKERS` background workers backfill every project that has none, salvaging what they can when old assets are missing. An upload without history generates it straight away, needs every asset, and is still saved if generation fails. + +A remix's history is built on its parent's, at the base commit recorded for the remix, so the parent's history is generated first. A missing base never leads to a new root commit or to using the parent's current head. When the parent can't be read or its history can't be copied yet, generation fails and the project is left as it was, so the next upload or the next server start tries again. A deleted parent or an unrecorded base commit fails the same way, and only succeeds if the parent comes back or the original history is restored. A project whose recorded edits go beyond its base needs its original repository and always fails. + +The first start after history sizes were recorded measured the history of existing projects once, from local copies and the R2 inventory. The `migration:project-history-bytes-v1` diagnostic record marks it done. + +Upload callers hold the project's save lock (`project-history-`). History preparation takes that lock itself, after resolving ancestors, and checks the saved source hasn't changed since. So an upload releases its lock while history is prepared and takes it back afterwards. That avoids deadlocking on its own lock and holding nested locks across a chain of remix ancestors. + +### Serving snapshots + +Project, release and report-evidence snapshots are served from the local copy while one exists. Otherwise the API fetches the object from R2 through a presigned URL and passes it on as stored, with `Content-Encoding: gzip` when the stored copy is gzipped: + +- The fetch asks for `Accept-Encoding: identity`, so the HTTP client doesn't decompress R2's body before it's passed on. +- The body is a raw binary string. Code handling it must not assert it as `byte[]`, which would base64-decode it. +- R2 answering 404 is a real 404, and so is a missing local copy when R2 isn't configured. Any other failure, such as a refused credential or an R2 outage, answers 502 `project snapshot unavailable` rather than saying the project has no snapshot. So does an empty body, or one over 20 MiB. + ## Storage limits -Each plan has a total storage limit: 500 MB on Free, 2 GB on Lite, 10 GB on Plus and 50 GB on Pro. A user's usage is the sum of every project they own, trashed projects included. Each project counts its assets, its compressed project JSON and its history archive, even when an asset is shared with other projects. Saving is checked against the owner's limit before anything is stored. A save may make a project bigger only while it fits in the free space, so a user over the limit can still save a project at its current size or smaller. Assets uploaded ahead of a save count as pending until a saved project references them, or for 7 days. Deleting a project frees its space once it is removed from the trash. Backpack items count toward the same limit, and deleting one frees its space straight away. `GET /v1/me/quota` returns `used`, `pending`, `limit`, `remaining`, `backpack` (the bytes held in the backpack) and the five largest projects. On first start after this change, the server measures the history size of existing projects from local copies and the R2 inventory. +MistWarp has no total storage limit of its own for Rotur accounts. Their projects, assets and backpack items count against the person's one Rotur storage allowance, which their Rotur plan sets and which they share with Rotur's other apps. The Rotur API keeps the count in its storage ledger, under three objects for MistWarp: + +| Object | Counts | +| --- | --- | +| `projects` | `project.json` snapshots, including the ones releases keep, and history archives | +| `assets` | Costumes and sounds | +| `backpack` | Backpack item bodies | + +Projects in the trash count until they're permanently deleted. Each blob counts once per person, however many of their projects use it: a costume in ten of their projects counts once, and so does a remix's `project.json` until the remix is first saved. Counting is per person: two people using the same asset each count it, though it's stored once. Thumbnails, share cards and backpack previews don't count. + +### Holding and settling + +1. Before something is stored, mistwarp-api works out each object's new total. Any object that would grow is reserved at its new total, and the ledger only holds the difference. When that doesn't fit, the request answers 413 with the code `storage_full`. Saves, uploads, remixes and the backpack also send `shared: true`, `used`, `limit`, `remaining`, `needed` and `membershipUrl`; transferring a project to a new owner only sends `error` and `needed`. A change that leaves every object at or below what the ledger already counts always fits. Admins aren't stopped by a full allowance. +2. Once it's stored, the totals are worked out again from what's really there and the ledger is set to them, which commits the reservation. A reservation that is never committed or released expires on its own, after the ledger's default of an hour. +3. Permanently deleting a project from the trash, deleting backpack items and anything else that only frees space doesn't reserve anything. It settles a couple of seconds later, once however many changes arrive meanwhile. Deleting a project only moves it to the trash, where it still counts. + +Every six hours, starting two minutes after the server starts, everyone is settled. That catches anything a settle missed while Rotur couldn't be reached. When Rotur can't be reached or answers with an error, MistWarp saves anyway rather than lose someone's work, and the next settle counts it. + +Someone who stores more than their allowance, for example after their plan ends, keeps everything they have. The ledger stays at what it last counted for them, and they can't add more until they're back under it. + +An asset uploaded ahead of the save that uses it holds room for up to a week. The hold is released when a save references the asset, or when its upload fails. Deleting an account frees everything MistWarp counted for it. + +Without `ROTUR_SERVICE_SECRET`, or with a `ROTUR_LOCAL_API_URL` that isn't a loopback address (see [Configuration](/backend/configuration)), the server logs a warning at start and nothing is counted or refused for Rotur accounts. + +### Classroom students + +Classroom students aren't Rotur accounts, so they stay outside the ledger. Their class's plan gives them storage, shared by every student in the plan's classes: 1 GiB on the free plan, 25 GiB on Classroom and 250 GiB on School. An admin can set another amount on a paid plan, but not on the free one. A student's count includes their backpack, and each of their projects counts its assets, compressed `project.json` and history archive, even when an asset is shared with another project, and assets uploaded ahead of a save count as pending for up to 7 days. + +### Quota + +`GET /v1/me/quota` returns: + +| Field | Value | +| --- | --- | +| `shared` | `true` for Rotur accounts, `false` for classroom students | +| `known` | `false` when Rotur couldn't say. `used`, `limit` and `remaining` are then 0 | +| `used`, `limit`, `remaining` | For a Rotur account, their whole Rotur storage, including other apps. For a student, `used` is their own storage and `limit` is that plus what's left in their plan's shared pool | +| `pending` | Bytes uploaded ahead of a save. Always 0 for Rotur accounts. When Rotur answered, their holds are part of `mistwarp` | +| `mistwarp` | MistWarp's part of `used`: what the ledger counts plus what it holds. When Rotur can't say, MistWarp's own measure of what's stored, without holds | +| `backpack` | The bytes held in the backpack | +| `largest` | The five largest projects, trashed ones included, as `id`, `title`, `bytes` and `trashed`. Each project's `bytes` includes every asset it uses, so a shared asset shows in each | +| `membershipUrl` | Where to get more Rotur storage | + + +### Backfilling the ledger + +Rotur's one-off `claw storage-backfill` loads what MistWarp already stores into the ledger. Make its input with the API stopped: + +```sh +./main storage-report +``` + +It measures any release snapshots without a recorded size, writes `{service: "mistwarp", accounts: {: {projects, assets, backpack}}}` to the file and exits. Only accounts that store something are listed, and an object they don't use is left out. ## Backpack @@ -45,7 +115,7 @@ The editor backpack syncs to the signed-in account. Items are scripts, sprites, | Route | Purpose | | --- | --- | | `GET /v1/me/backpack?type=&offset=&limit=` | Newest first, up to 100 per page, with `total`, `count` and `bytes` | -| `POST /v1/me/backpack` | Multipart `type`, `mime`, `name`, `body`, and optional `thumbnail` with `thumbnailMime`; checked against the storage limit | +| `POST /v1/me/backpack` | Multipart `type`, `mime`, `name`, `body`, and optional `thumbnail` with `thumbnailMime`; checked against their Rotur storage, or class storage for students | | `PATCH /v1/me/backpack/:id` | Rename with `{name}` | | `DELETE /v1/me/backpack/:id` | Delete one item | | `POST /v1/me/backpack/delete` | Delete several with `{ids}`; returns `deleted` and `freedBytes` |