Fork card: unavailable is not confirmed, request_id makes a retry safe, forbidden precedes a bad body
Some checks failed
CultMesh QUIC native / Build win32-x64 (pull_request) Has been skipped
CultMesh QUIC native / Build linux-x64 (pull_request) Has been skipped
CultMesh QUIC native / Release native binaries (pull_request) Has been skipped
CultMesh QUIC native / Verify committed binaries match SHA256SUMS (pull_request) Has been cancelled
CultMesh portability and performance / ubuntu-latest reactive semantics and leases (pull_request) Has been cancelled
Some checks failed
CultMesh QUIC native / Build win32-x64 (pull_request) Has been skipped
CultMesh QUIC native / Build linux-x64 (pull_request) Has been skipped
CultMesh QUIC native / Release native binaries (pull_request) Has been skipped
CultMesh QUIC native / Verify committed binaries match SHA256SUMS (pull_request) Has been cancelled
CultMesh portability and performance / ubuntu-latest reactive semantics and leases (pull_request) Has been cancelled
unavailable now says the outcome is NOT CONFIRMED (a timeout after Huginn had the request may have stored it). The answer request and the stored desk_answer carry a client-set request_id: a retry with the same id and body returns the stored outcome and never adds a Revision; the same id with another body is request_id_conflict (409). A non-Active member with a bad body gets forbidden first. Scenarios: unavailable-then-retry (stored and not stored), replayed Refused, conflict, same id from another account, forbidden before the body. Both judges follow; vectors regenerated. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
soul
parent
32d63fe9ee
commit
b53491f3aa
6 changed files with 1702 additions and 454 deletions
File diff suppressed because one or more lines are too long
|
|
@ -22,7 +22,7 @@ All documents are CultNet map-mode: every key written, nil where absent, closed
|
|||
| `gamecult.fork.list.v0` | a page of entries, counts and a stamp | Bifrost, projected from Huginn |
|
||||
| `gamecult.fork.read_request.v0` | read one fork (Transport) | the desk |
|
||||
| `gamecult.fork.entry.v0` | one card with its record | Bifrost, projected from Huginn |
|
||||
| `gamecult.fork.unavailable.v0` | the second door or Huginn is down; try again | Bifrost |
|
||||
| `gamecult.fork.unavailable.v0` | the outcome is not confirmed (the second door or Huginn did not answer); retry with the same `request_id` | Bifrost |
|
||||
|
||||
### card
|
||||
|
||||
|
|
@ -50,11 +50,11 @@ Vectors `optionsHash`: the seven of the binding file (`heimdall_A..G`), computed
|
|||
|
||||
### answer_request
|
||||
|
||||
`{schemaVersion, fork_id, options_hash, answer, retracted, retracts, answered_at}`. `answer` is `{choice, note}` (at least one non-nil) or nil on a retraction. `choice` is an option id; `note` is the person's words, verbatim, 1 to 4000 **UTF-8 bytes**, not blank. A schema counts characters, not bytes, so its `maxLength: 4000` (code points) is only the looser bound and both suites enforce the byte limit as a rule: 4000 ASCII bytes pass; 1000 astral characters (4000 bytes) pass and 1001 (4004) fail; `e` plus a combining acute is 3 bytes, so 1333 of them and an `x` pass and 1334 fail; 1999 two-byte characters plus three ASCII (4001 bytes) fail. A note over the limit is `body_invalid`. `answered_at` is the client's claim. **A request never carries `answerer` or `authority`**: both are stamped by Huginn (`answerer` from the verified subject the receiver passes; `authority` from the door's configuration). A body that names either key at any depth is refused whole, never stripped (`body_forbidden_field`); any other unknown key is `body_unknown_field`. The request type Bifrost sends over the second door is this document; it has no field for either key, so a client cannot supply them by construction, and Bifrost's scan is the first line, not the only one. How Huginn receives the verified subject is the door's authenticated context, not a body field (open choice 3). In map-mode `retracted` is always written (the binding file's optional `retracted` becomes `false`).
|
||||
`{schemaVersion, fork_id, options_hash, answer, retracted, retracts, answered_at, request_id}`. **`request_id`** is set by the client, a lowercase D-format UUID, one per intended answer, kept across retries; the first stored answer that carries it binds it to the stamped `answerer`. A **retry with the same `request_id` and the same body returns the stored outcome unchanged** (a `Refused` one included, a `stale_fork` with the card it carried) and **never adds a Revision**; the same `request_id` with a different body is `request_id_conflict` (409, a refusal, nothing stored). The same id from another account is another request. A body refused at step 1 or 2 binds nothing, so its id is free to reuse. The lookup comes after steps 1 and 2 and before the fork is looked up, so a retry gets its stored outcome even if the card has since changed. `answer` is `{choice, note}` (at least one non-nil) or nil on a retraction. `choice` is an option id; `note` is the person's words, verbatim, 1 to 4000 **UTF-8 bytes**, not blank. A schema counts characters, not bytes, so its `maxLength: 4000` (code points) is only the looser bound and both suites enforce the byte limit as a rule: 4000 ASCII bytes pass; 1000 astral characters (4000 bytes) pass and 1001 (4004) fail; `e` plus a combining acute is 3 bytes, so 1333 of them and an `x` pass and 1334 fail; 1999 two-byte characters plus three ASCII (4001 bytes) fail. A note over the limit is `body_invalid`. `answered_at` is the client's claim. **A request never carries `answerer` or `authority`**: both are stamped by Huginn (`answerer` from the verified subject the receiver passes; `authority` from the door's configuration). A body that names either key at any depth is refused whole, never stripped (`body_forbidden_field`); any other unknown key is `body_unknown_field`. The request type Bifrost sends over the second door is this document; it has no field for either key, so a client cannot supply them by construction, and Bifrost's scan is the first line, not the only one. How Huginn receives the verified subject is the door's authenticated context, not a body field (open choice 3). In map-mode `retracted` is always written (the binding file's optional `retracted` becomes `false`).
|
||||
|
||||
### desk_answer (the stored kind)
|
||||
|
||||
`{schemaVersion, answer_id, fork_id, outcome, of, retracts, code, options_hash, choice, note, answered_at, received_at, claim_in_future, answerer, authority}`, key `<campaign>:desk_answer:<question-label>.n<seq>`; `answer_id` is `n<seq>`, assigned by Huginn per question, and **an answer is named by its answer id** everywhere (`retracts`, `of`, `ruled_from`).
|
||||
`{schemaVersion, answer_id, fork_id, outcome, of, retracts, code, options_hash, choice, note, answered_at, received_at, claim_in_future, answerer, authority, request_id}`, key `<campaign>:desk_answer:<question-label>.n<seq>`; `answer_id` is `n<seq>`, assigned by Huginn per question, and **an answer is named by its answer id** everywhere (`retracts`, `of`, `ruled_from`).
|
||||
|
||||
The stamped `authority` field of a stored answer is an **attribution**: the role the verified account holds (`Operator`, `Steward`, `Member`), copied from Bifrost's state. A stored answer confers no authority. Authority exists only where a ruling cites a counted answer ("Operator authority" below); the field keeps the binding file's spelling (open choice 8). One tagged `outcome`, each variant carrying only its own link:
|
||||
|
||||
|
|
@ -63,7 +63,7 @@ The stamped `authority` field of a stored answer is an **attribution**: the role
|
|||
- `Retraction`: the stored form of `retracted: true` plus `retracts`. `retracts` names the answer retracted; `choice` and `note` nil. The illegal pair (a retraction with no target, or a target with no retraction) cannot be written.
|
||||
- `Refused`: any refusal from steps 4 to 7 or R1 and R2, with its `code`, stored too. `choice` and `note` keep what the body carried.
|
||||
|
||||
`received_at` is Huginn's admission time; "first" means first by admission order (the `n<seq>` ordinal), never by `answered_at`. `claim_in_future` is true when `answered_at` is more than five minutes after `received_at`: accepted but flagged. **Not stored, and no answer id:** a body refused at step 1 or 2 (Bifrost; it never reaches Huginn), and a body naming an unknown fork (step 3; Huginn answers it from its stored forks, but with no question there is nothing to key a record under). Each gets a `refusal` and is dropped. A malformed body is therefore never stored, and neither is an unknown fork. Every refusal from step 4 on is stored. **`unavailable`** (503) is not a refusal and not in the refusal set: Bifrost answers it when the second door or Huginn cannot be reached after steps 1 and 2 passed (a bad body is still refused first). It carries no answer id, stores nothing, and covers **calls 1 and 2 as well as the answer POST** when Huginn cannot be reached (Transport), and tells the desk to try the same request again (`retryAfterSeconds`, nil when Bifrost has no hint).
|
||||
`received_at` is Huginn's admission time; "first" means first by admission order (the `n<seq>` ordinal), never by `answered_at`. `claim_in_future` is true when `answered_at` is more than five minutes after `received_at`: accepted but flagged. **Not stored, and no answer id:** a body refused at step 1 or 2 (Bifrost; it never reaches Huginn), and a body naming an unknown fork (step 3; Huginn answers it from its stored forks, but with no question there is nothing to key a record under). Each gets a `refusal` and is dropped. A malformed body is therefore never stored, and neither is an unknown fork. Every refusal from step 4 on is stored. **`unavailable`** (503) is not a refusal and not in the refusal set: Bifrost answers it when the second door or Huginn did not answer after the auth steps and the body shape passed (a bad body is still refused first). **It says the outcome is NOT CONFIRMED, never that nothing was stored**: a timeout after the request reached Huginn may have stored it. It carries no answer id. The desk retries the same request with the same `request_id` and learns the outcome: the stored one if Huginn had it, a fresh one if not. It covers **calls 1 and 2 as well as the answer POST** when Huginn cannot be reached (Transport; a read has no outcome to confirm, so a retry is plain). `retryAfterSeconds` is nil when Bifrost has no hint.
|
||||
|
||||
### Counting rules (in order; the first failure refuses with that code)
|
||||
|
||||
|
|
@ -106,15 +106,15 @@ Source: the desk's client needs (Ratatoskr PR #24 section 12, `ratatoskr-desk-sp
|
|||
|
||||
Calls 1 and 2 are enough for a read-only desk. Every response is the pinned MessagePack document or its JSON form with the same keys (open choice 1 of `vote-api.md`: the media type is unsettled).
|
||||
|
||||
**Auth, in order, per route.** (1) A bearer, else `unauthenticated` (401). (2) The token's audience is `bifrost-desk`: **the Matrix Authentication Service token chat holds today is refused, and so is any `votes.*` token** (audience `bifrost-votes`), both as `unauthenticated`. (3) The scope the route needs, else `insufficient_scope` (403): `desk.read` for calls 1 and 2, `desk.answer` for call 3, and neither implies the other. (4) The account behind `sub` is an Active member, else `forbidden` (403), as in the vote API; scope is judged first. (5) Only then is Huginn asked, so `unavailable` never hides an auth refusal. A `votes.*` token therefore touches none of the three. For call 3 the body is then shaped (steps 1 and 2 above) and a body naming `answerer` or `authority` at any depth is `body_forbidden_field`. Heimdall's file leaves the audience and the claims check open; `insufficient_scope`, `forbidden` and `request_invalid` (400, a list or read request that fails its document) are added to the door refusals.
|
||||
**Auth, in order, per route.** (1) A bearer, else `unauthenticated` (401). (2) The token's audience is `bifrost-desk`: **the Matrix Authentication Service token chat holds today is refused, and so is any `votes.*` token** (audience `bifrost-votes`), both as `unauthenticated`. (3) The scope the route needs, else `insufficient_scope` (403): `desk.read` for calls 1 and 2, `desk.answer` for call 3, and neither implies the other. (4) The account behind `sub` is an Active member, else `forbidden` (403), as in the vote API; scope is judged first. (5) For call 3 the body is then shaped (steps 1 and 2 above), so **a non-Active member who sends a bad body, including one naming `answerer` or `authority`, gets `forbidden`, not a body refusal**; a body naming either key at any depth is `body_forbidden_field` only for an Active member. (6) Only then is Huginn asked, so `unavailable` never hides an auth or body refusal. A `votes.*` token touches none of the three. Heimdall's file leaves the audience and the claims check open; `insufficient_scope`, `forbidden`, `request_invalid` (400, a list or read request that fails its document) and `request_id_conflict` are added to the door refusals.
|
||||
|
||||
**List.** `list_request`: `{mind, status, cursor, limit}`. `mind` is the Mind's instance slug. `status` is `open`, `recorded` or nil for both; `recorded` means a closed card. Cards come **newest first by `order`** (the admission ordinal). `limit` is 0 to 50; **`limit` 0 returns no entries, only the counts and the stamp**, which is what "N open" on the Mind's header needs. `cursor` is nil or `c<N>`: the cards whose `order` is below N; a client treats it as opaque and sends back the `next_cursor` it was given. `list`: `{mind, stamp, open_count, recorded_count, forks[entry], next_cursor}`. The counts cover every card the viewer may see, whatever `status` and `cursor` asked for. `stamp` is `s<N>`, N the receiver's last-seen Huginn admission ordinal for the Mind's desk documents: the same stamp means the same state, so a desk polls `limit` 0 and fetches bodies only when the stamp moves. `next_cursor` is nil on the last page. An `entry` is `{card, record}`: the card and its `record` (the answers with their outcomes and the derived `counted_answer_id`).
|
||||
|
||||
**Read.** `entry` for one fork. Its `card.options_hash` is **computed by the server** from the five shown members as in "Options hash" and the client recomputes it from what it rendered; a card whose hash is not the hash of its members is no card (negative vector `card_hash_wrong`). The record's `fork_id` and `options_hash` are the card's, and `counted_answer_id` is derived, not copied (negative vectors for each). Which cards and answers a viewer may see follows the card's audience (PR #24 section 5); a fork the viewer may not see is `fork_unknown`, not a different refusal.
|
||||
|
||||
**Answer.** The body is the `answer_request` and nothing else a client may set: `fork_id`, `options_hash`, `answer`, `answered_at` (plus `retracted` and `retracts`, written `false` and nil unless the call retracts). The response is the stored outcome: `Counted`, `Revision`, `Retraction`, or `Refused` with its code. **A `stale_fork` refusal carries the current card** in `answer_result.card`, so the desk can show the new fork without another read. Nothing is stored for a step 1 or 2 refusal or an unknown fork, and nothing for `unavailable`.
|
||||
**Answer.** The body is the `answer_request` and nothing else a client may set: `fork_id`, `options_hash`, `answer`, `answered_at`, `request_id` (plus `retracted` and `retracts`, written `false` and nil unless the call retracts). The response is the stored outcome: `Counted`, `Revision`, `Retraction`, or `Refused` with its code. **A `stale_fork` refusal carries the current card** in `answer_result.card`, so the desk can show the new fork without another read. Nothing is stored for a step 1 or 2 refusal, an unknown fork or a `request_id_conflict`. `unavailable` promises nothing either way.
|
||||
|
||||
**Vectors (`transport` in `fork-card-vectors.json`).** `listRequest`, `readRequest` and `entry` (valid and invalid, with bytes); `listInvalid`; `listScenarios` (five scenarios over one Mind's five cards: paged open-only, recorded-only, all, `limit` 0, an empty Mind, each response with its bytes, the cursor of page two being page one's `next_cursor`); `authCases` (twenty-two cases: the MAS token, three `votes.*` tokens, a desk token with the other route's scope, a non-Active member on each route, and Huginn down on each route, with auth and membership judged first). Both suites replay the list requests through a reference judge and the auth cases through another. Top-level `unavailable` pins the 503 document, and two scenarios pin that an unreachable door stores nothing and that a bad body is refused before the door is asked.
|
||||
**Vectors (`transport` in `fork-card-vectors.json`).** `listRequest`, `readRequest` and `entry` (valid and invalid, with bytes); `listInvalid`; `listScenarios` (five scenarios over one Mind's five cards: paged open-only, recorded-only, all, `limit` 0, an empty Mind, each response with its bytes, the cursor of page two being page one's `next_cursor`); `authCases` (twenty-two cases: the MAS token, three `votes.*` tokens, a desk token with the other route's scope, a non-Active member on each route, and Huginn down on each route, with auth and membership judged first). Both suites replay the list requests through a reference judge and the auth cases through another. Top-level `unavailable` pins the 503 document. Scenarios pin: an `unavailable` where Huginn never had the request, retried into a `Counted` answer; an `unavailable` where Huginn had stored it, whose retry returns the stored outcome and adds no Revision; a replayed `Refused` with its card; `request_id_conflict`; the same id from another account; and a non-Active member with a bad body, with the door down, getting `forbidden` first. A bad body is refused before the door is asked.
|
||||
|
||||
**Bifrost must still build:** all three routes; the `bifrost-desk` audience and the `desk.read` and `desk.answer` scopes on the OIDC token it issues to chat; the projection of cards and records from Huginn, the stamp, the cursor and the counts; the `DeskAnswer` call on the second door and the pass-through of its outcome; the `unavailable` answer. **Huginn must still build** the second door's wire and the read side the projection uses (Eureka's cut spec, after her record PR). **The desk may build today** against the vectors: nothing in them needs a live service.
|
||||
|
||||
|
|
|
|||
|
|
@ -250,7 +250,8 @@
|
|||
"answer",
|
||||
"retracted",
|
||||
"retracts",
|
||||
"answered_at"
|
||||
"answered_at",
|
||||
"request_id"
|
||||
],
|
||||
"properties": {
|
||||
"schemaVersion": {
|
||||
|
|
@ -287,6 +288,9 @@
|
|||
},
|
||||
"answered_at": {
|
||||
"$ref": "#/$defs/instant"
|
||||
},
|
||||
"request_id": {
|
||||
"$ref": "#/$defs/requestId"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
|
@ -308,7 +312,8 @@
|
|||
"received_at",
|
||||
"claim_in_future",
|
||||
"answerer",
|
||||
"authority"
|
||||
"authority",
|
||||
"request_id"
|
||||
],
|
||||
"properties": {
|
||||
"schemaVersion": {
|
||||
|
|
@ -369,6 +374,9 @@
|
|||
},
|
||||
"authority": {
|
||||
"$ref": "#/$defs/id"
|
||||
},
|
||||
"request_id": {
|
||||
"$ref": "#/$defs/requestId"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
|
@ -390,7 +398,8 @@
|
|||
"received_at",
|
||||
"claim_in_future",
|
||||
"answerer",
|
||||
"authority"
|
||||
"authority",
|
||||
"request_id"
|
||||
],
|
||||
"properties": {
|
||||
"schemaVersion": {
|
||||
|
|
@ -451,6 +460,9 @@
|
|||
},
|
||||
"authority": {
|
||||
"$ref": "#/$defs/id"
|
||||
},
|
||||
"request_id": {
|
||||
"$ref": "#/$defs/requestId"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
|
@ -472,7 +484,8 @@
|
|||
"received_at",
|
||||
"claim_in_future",
|
||||
"answerer",
|
||||
"authority"
|
||||
"authority",
|
||||
"request_id"
|
||||
],
|
||||
"properties": {
|
||||
"schemaVersion": {
|
||||
|
|
@ -519,6 +532,9 @@
|
|||
},
|
||||
"authority": {
|
||||
"$ref": "#/$defs/id"
|
||||
},
|
||||
"request_id": {
|
||||
"$ref": "#/$defs/requestId"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
|
@ -540,7 +556,8 @@
|
|||
"received_at",
|
||||
"claim_in_future",
|
||||
"answerer",
|
||||
"authority"
|
||||
"authority",
|
||||
"request_id"
|
||||
],
|
||||
"properties": {
|
||||
"schemaVersion": {
|
||||
|
|
@ -608,6 +625,9 @@
|
|||
},
|
||||
"authority": {
|
||||
"$ref": "#/$defs/id"
|
||||
},
|
||||
"request_id": {
|
||||
"$ref": "#/$defs/requestId"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
|
@ -675,7 +695,8 @@
|
|||
"fork_unknown",
|
||||
"insufficient_scope",
|
||||
"forbidden",
|
||||
"request_invalid"
|
||||
"request_invalid",
|
||||
"request_id_conflict"
|
||||
]
|
||||
},
|
||||
"error": {
|
||||
|
|
@ -928,7 +949,13 @@
|
|||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "The outcome is NOT CONFIRMED: the request may have reached Huginn and been stored before the reply was lost. Retry with the same request_id to learn the outcome."
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string",
|
||||
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
|
||||
"description": "Set by the client, a lowercase D-format UUID. Bound to the stamped answerer by the first stored answer that carries it."
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@ import assert from "node:assert/strict";
|
|||
import { createHash } from "node:crypto";
|
||||
import { readFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { isDeepStrictEqual } from "node:util";
|
||||
|
||||
import Ajv2020 from "ajv/dist/2020.js";
|
||||
import { decode, encode } from "@msgpack/msgpack";
|
||||
|
|
@ -202,8 +203,10 @@ const TAILS: Record<string, string> = {
|
|||
body_unknown_field: "the body is a closed shape",
|
||||
body_invalid: "the body does not satisfy gamecult.fork.answer_request.v0",
|
||||
fork_unknown: "no such fork",
|
||||
forbidden: "only Active members may use the desk",
|
||||
request_id_conflict: "this request_id was used for a different body",
|
||||
};
|
||||
const REQUEST_KEYS = ["schemaVersion", "fork_id", "options_hash", "answer", "retracted", "retracts", "answered_at"];
|
||||
const REQUEST_KEYS = ["schemaVersion", "fork_id", "options_hash", "answer", "retracted", "retracts", "answered_at", "request_id"];
|
||||
const hasKey = (v: unknown, names: string[]): boolean =>
|
||||
typeof v === "object" && v !== null && Object.entries(v).some(([k, x]) => names.includes(k) || hasKey(x, names));
|
||||
const SECONDS = (iso: string): number => Date.parse(iso);
|
||||
|
|
@ -213,6 +216,7 @@ function judge(start: Card, steps: { kind: string; body: Record<string, any> | n
|
|||
let card = start;
|
||||
const answers: Record<string, any>[] = [];
|
||||
const responses: unknown[] = [];
|
||||
const seen = new Map<string, { body: Record<string, any>; response: unknown }>(); // (answerer, request_id) -> the first stored outcome
|
||||
const counted = (): string | null => {
|
||||
const hash = optionsHash(card);
|
||||
const live = answers.find((a) => (a.outcome === "Counted" || a.outcome === "Revision") && a.options_hash === hash
|
||||
|
|
@ -229,17 +233,23 @@ function judge(start: Card, steps: { kind: string; body: Record<string, any> | n
|
|||
const doc = { schemaVersion: "gamecult.desk_answer.v0", answer_id: s.answer_id, fork_id: b.fork_id, outcome,
|
||||
of: outcome === "Revision" ? link : null, retracts: outcome === "Retraction" ? link : null, code: outcome === "Refused" ? code : null,
|
||||
options_hash: b.options_hash, choice: a.choice, note: a.note, answered_at: b.answered_at, received_at: s.received_at,
|
||||
claim_in_future: SECONDS(b.answered_at) - SECONDS(s.received_at) > 300_000, answerer: s.answerer, authority: s.authority };
|
||||
claim_in_future: SECONDS(b.answered_at) - SECONDS(s.received_at) > 300_000, answerer: s.answerer, authority: s.authority, request_id: b.request_id };
|
||||
answers.push(doc);
|
||||
return { schemaVersion: "gamecult.fork.answer_result.v0", answer: doc, card: code === "stale_fork" ? card : null };
|
||||
const stored = { schemaVersion: "gamecult.fork.answer_result.v0", answer: doc, card: code === "stale_fork" ? card : null };
|
||||
seen.set(`${s.answerer}|${b.request_id}`, { body: structuredClone(b), response: structuredClone(stored) });
|
||||
return stored;
|
||||
};
|
||||
const refuse = (code: string) => store("Refused", null, code);
|
||||
const down = s.door_down === true, reached = s.stored === true; // the second door failed to answer; "stored" says whether Huginn had the request by then
|
||||
const unavailable = () => ({ schemaVersion: "gamecult.fork.unavailable.v0", code: "unavailable", error: "unavailable: the outcome is not confirmed, try again with the same request_id", retryAfterSeconds: s.retry_after_seconds });
|
||||
let response: unknown;
|
||||
if (s.answerer === null) response = door("unauthenticated");
|
||||
else if (s.active === false) response = door("forbidden");
|
||||
else if (hasKey(b, ["answerer", "authority"])) response = door("body_forbidden_field");
|
||||
else if (Object.keys(b).some((k) => !REQUEST_KEYS.includes(k)) || (b.answer && Object.keys(b.answer).some((k) => k !== "choice" && k !== "note"))) response = door("body_unknown_field");
|
||||
else if (!check(forkSchema, "answerRequest", b) || noteRuleErrors("answerRequest", b).length > 0 || (!b.retracted && b.answer === null)) response = door("body_invalid");
|
||||
else if (s.door_down) response = { schemaVersion: "gamecult.fork.unavailable.v0", code: "unavailable", error: "unavailable: the answer path is down, try again", retryAfterSeconds: s.retry_after_seconds };
|
||||
else if (down && !reached) response = unavailable();
|
||||
else if (seen.has(`${s.answerer}|${b.request_id}`)) { const prior = seen.get(`${s.answerer}|${b.request_id}`)!; response = isDeepStrictEqual(prior.body, b) ? structuredClone(prior.response) : door("request_id_conflict"); }
|
||||
else if (b.fork_id !== card.fork_id) response = door("fork_unknown");
|
||||
else if (b.options_hash !== optionsHash(card)) response = refuse("stale_fork");
|
||||
else if (!card.deciders.includes(s.answerer)) response = refuse("not_a_decider");
|
||||
|
|
@ -254,7 +264,7 @@ function judge(start: Card, steps: { kind: string; body: Record<string, any> | n
|
|||
const first = counted();
|
||||
response = first === null ? store("Counted", null, null) : store("Revision", first, null);
|
||||
}
|
||||
responses.push(response);
|
||||
responses.push(down && reached ? unavailable() : response);
|
||||
}
|
||||
return { responses, record: { schemaVersion: "gamecult.fork.record.v0", fork_id: card.fork_id, options_hash: optionsHash(card), counted_answer_id: counted(), answers } };
|
||||
}
|
||||
|
|
@ -273,10 +283,12 @@ test("fork card: every scenario replays to the vector's responses and record, by
|
|||
});
|
||||
|
||||
test("fork card: a body refused at the door or naming an unknown fork is never stored", () => {
|
||||
const door = new Set(["unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "unavailable"]);
|
||||
const door = new Set(["unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "forbidden", "request_id_conflict"]);
|
||||
let doorRefusals = 0;
|
||||
for (const sc of fork.scenarios) {
|
||||
for (const s of sc.steps) {
|
||||
// unavailable promises nothing: the outcome is not confirmed, so the answer is stored exactly when Huginn had it
|
||||
if (s.response?.code === "unavailable") assert.equal(sc.record.answers.some((a: { answer_id: string }) => a.answer_id === s.server.answer_id), s.server.stored === true, `${sc.name} unavailable`);
|
||||
if (s.response && door.has(s.response.code)) {
|
||||
doorRefusals++;
|
||||
assert.ok(!sc.record.answers.some((a: { answer_id: string }) => a.answer_id === s.server.answer_id), `${sc.name} stored a door refusal`);
|
||||
|
|
@ -292,7 +304,7 @@ test("fork card: the scenarios cover every outcome and every refusal code", () =
|
|||
for (const s of sc.steps) if (s.response) seen.add(s.response.code ?? s.response.answer.code ?? s.response.answer.outcome);
|
||||
for (const a of sc.record.answers) seen.add(a.outcome);
|
||||
}
|
||||
for (const want of ["Counted", "Revision", "Retraction", "Refused", "unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "unavailable", "stale_fork", "not_a_decider",
|
||||
for (const want of ["Counted", "Revision", "Retraction", "Refused", "unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "unavailable", "forbidden", "request_id_conflict", "stale_fork", "not_a_decider",
|
||||
"fork_closed", "choice_invalid", "bad_retraction", "already_retracted"]) {
|
||||
assert.ok(seen.has(want), want);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -208,20 +208,24 @@ hv("astral_option_id_and_text", card(options=[{"id": "\U0001F600", "text": "\U00
|
|||
assert [h["sha256"] for h in hashes if h["heimdall"] == "D"] == [h["sha256"] for h in hashes if h["heimdall"] == "E"]
|
||||
assert len({h["sha256"] for h in hashes if h["name"] in ("heimdall_A_five_members", "hidden_members_do_not_move_it")}) == 1
|
||||
|
||||
def body(choice=None, note=None, h=None, at="2026-11-12T19:02:00Z", fork=FID, retracts=None, answer="auto"):
|
||||
RID = [0]
|
||||
def next_rid():
|
||||
RID[0] += 1; n = RID[0]
|
||||
return f"{n:08x}-0000-4000-8000-{n:012x}"
|
||||
def body(choice=None, note=None, h=None, at="2026-11-12T19:02:00Z", fork=FID, retracts=None, answer="auto", rid=None):
|
||||
a = {"choice": choice, "note": note} if answer == "auto" else answer
|
||||
if answer == "auto" and choice is None and note is None: a = None
|
||||
return {"schemaVersion": "gamecult.fork.answer_request.v0", "fork_id": fork, "options_hash": h or H, "answer": a,
|
||||
"retracted": retracts is not None, "retracts": retracts, "answered_at": at}
|
||||
"retracted": retracts is not None, "retracts": retracts, "answered_at": at, "request_id": rid or next_rid()}
|
||||
def retraction(target, **kw): return body(retracts=target, **kw)
|
||||
NOTE = "Keep it local: a slot mark is the author's call, and sharing it is a separate act."
|
||||
def srv(aid, who, at, auth="Operator"): return {"answer_id": aid, "answerer": who, "authority": auth, "received_at": at}
|
||||
TAIL = {"unauthenticated": "a verified session is required", "body_forbidden_field": "answerer and authority are set by the receiver", "body_unknown_field": "the body is a closed shape",
|
||||
"body_invalid": "the body does not satisfy gamecult.fork.answer_request.v0", "fork_unknown": "no such fork",
|
||||
"insufficient_scope": "the token lacks the scope this route needs", "forbidden": "only Active members may use the desk", "request_invalid": "the request does not satisfy its document"}
|
||||
"insufficient_scope": "the token lacks the scope this route needs", "forbidden": "only Active members may use the desk", "request_id_conflict": "this request_id was used for a different body", "request_invalid": "the request does not satisfy its document"}
|
||||
DOOR = set(TAIL)
|
||||
def refusal_doc(code): return {"schemaVersion": "gamecult.fork.refusal.v0", "code": code, "error": f"{code}: {TAIL[code]}"}
|
||||
def unavailable_doc(retry=30): return {"schemaVersion": "gamecult.fork.unavailable.v0", "code": "unavailable", "error": "unavailable: the answer path is down, try again", "retryAfterSeconds": retry}
|
||||
def unavailable_doc(retry=30): return {"schemaVersion": "gamecult.fork.unavailable.v0", "code": "unavailable", "error": "unavailable: the outcome is not confirmed, try again with the same request_id", "retryAfterSeconds": retry}
|
||||
def future(a, r):
|
||||
import datetime as dt
|
||||
p = lambda x: dt.datetime.strptime(x, "%Y-%m-%dT%H:%M:%SZ")
|
||||
|
|
@ -231,7 +235,7 @@ def da(outcome, link, code, b, server):
|
|||
return {"schemaVersion": "gamecult.desk_answer.v0", "answer_id": server["answer_id"], "fork_id": b["fork_id"], "outcome": outcome,
|
||||
"of": link if outcome == "Revision" else None, "retracts": link if outcome == "Retraction" else None, "code": code if outcome == "Refused" else None,
|
||||
"options_hash": b["options_hash"], "choice": a["choice"], "note": a["note"], "answered_at": b["answered_at"], "received_at": server["received_at"],
|
||||
"claim_in_future": future(b["answered_at"], server["received_at"]), "answerer": server["answerer"], "authority": server["authority"]}
|
||||
"claim_in_future": future(b["answered_at"], server["received_at"]), "answerer": server["answerer"], "authority": server["authority"], "request_id": b["request_id"]}
|
||||
def result(answer, c=None): return {"schemaVersion": "gamecult.fork.answer_result.v0", "answer": answer, "card": c}
|
||||
def record(counted, answers, h=H, fork=FID): return {"schemaVersion": "gamecult.fork.record.v0", "fork_id": fork, "options_hash": h, "counted_answer_id": counted, "answers": answers}
|
||||
T = lambda m, sec=5: f"2026-11-12T19:{m:02d}:{sec:02d}Z"
|
||||
|
|
@ -262,6 +266,9 @@ RET = lambda t: retraction(t, at="2026-11-12T19:09:00Z")
|
|||
def sr(aid, who=OP, m=9, auth="Operator"): return srv(aid, who, T(m), auth)
|
||||
MATRIX = [step("matrix_event", None, None, None, matrix_kind=k, choice=c) for k, c in (("m.replace", "yes"), ("m.redaction", None), ("m.reaction", "yes"))]
|
||||
X1 = ok(x1, sx1, "Counted", None)
|
||||
REPLAY1 = (step("answer", x1, dict(sx1, answer_id="n9"), X1[0]["response"]), None)
|
||||
LOST = [(step("answer", x1, dict(sx1, door_down=True, stored=True, retry_after_seconds=30), unavailable_doc(30)), X1[1])]
|
||||
STALE_BODY = stale_body(); STALE_RF = rf(STALE_BODY, sx1, "stale_fork", c=CARD)
|
||||
scen = [
|
||||
sc("operator_answers_and_is_counted", CARD, [X1], "n1"),
|
||||
sc("choice_alone_is_counted", CARD, [ok(pick, sx1, "Counted", None)], "n1"),
|
||||
|
|
@ -272,11 +279,17 @@ scen = [
|
|||
sc("an_unknown_key_is_refused_the_body_is_closed", CARD, [door(dict(x1, mood="happy"), sx1, "body_unknown_field")], None),
|
||||
sc("an_answer_with_neither_choice_nor_note_is_invalid", CARD, [door(body(answer={"choice": None, "note": None}), sx1, "body_invalid")], None),
|
||||
sc("a_non_retraction_without_an_answer_is_invalid", CARD, [door(body(answer=None), sx1, "body_invalid")], None),
|
||||
sc("the_second_door_down_is_unavailable_and_stores_nothing", CARD, [step("answer", x1, dict(sx1, door_down=True, retry_after_seconds=30), unavailable_doc(30)), ok(x1, sx2, "Counted", None)], "n2"),
|
||||
sc("a_bad_body_is_refused_before_the_door_is_asked", CARD, [door(dict(x1, answerer="x"), dict(sx1, door_down=True, retry_after_seconds=30), "body_forbidden_field")], None),
|
||||
sc("unavailable_before_huginn_stored_nothing_is_retried_into_a_Counted_answer", CARD, [step("answer", x1, dict(sx1, answer_id="n9", door_down=True, retry_after_seconds=30), unavailable_doc(30)), ok(x1, sx1, "Counted", None)], "n1"),
|
||||
sc("unavailable_after_huginn_stored_the_retry_with_the_same_request_id_returns_the_stored_outcome", CARD, LOST + [REPLAY1], "n1"),
|
||||
sc("a_retry_never_adds_a_Revision", CARD, [X1, REPLAY1], "n1"),
|
||||
sc("a_refused_answer_replays_its_refusal_with_the_card_it_carried", CARD, [STALE_RF, (step("answer", STALE_BODY, dict(sx1, answer_id="n9"), STALE_RF[0]["response"]), None)], None),
|
||||
sc("the_same_request_id_with_another_body_is_request_id_conflict", CARD, [X1, door(dict(x1, answer={"choice": "yes", "note": None}), dict(sx1, answer_id="n9"), "request_id_conflict")], "n1"),
|
||||
sc("the_same_request_id_from_another_account_is_another_request", Y_CARD, [X1, ok(dict(y1, request_id=x1["request_id"]), sy1, "Revision", "n1")], "n1"),
|
||||
sc("a_non_active_member_is_forbidden_before_the_body_is_read", CARD, [door(dict(x1, answerer="x"), dict(sx1, active=False), "forbidden"), door(x1, dict(sx1, active=False), "forbidden"),
|
||||
door(dict(x1, mood="happy"), dict(sx1, active=False, door_down=True, retry_after_seconds=30), "forbidden")], None),
|
||||
sc("no_session_is_unauthenticated", CARD, [door(x1, srv("n1", None, T(2), None), "unauthenticated")], None),
|
||||
sc("an_unknown_fork_is_refused_at_the_door", CARD, [door(body("no", NOTE, fork="gamecult-chat:question:nope"), sx1, "fork_unknown")], None),
|
||||
sc("V2_stale_hash_is_refused_not_counted_and_stored_as_Refused", CARD, [rf(stale_body(), sx1, "stale_fork", c=CARD)], None),
|
||||
sc("V2_stale_hash_is_refused_not_counted_and_stored_as_Refused", CARD, [STALE_RF], None),
|
||||
sc("V2_a_stale_answer_then_a_fresh_one_the_fresh_one_is_counted", CARD, [rf(stale_body(), sx1, "stale_fork", c=CARD), ok(x1, sx2, "Counted", None)], "n2"),
|
||||
sc("V3_an_answer_off_the_decider_list_is_Refused_not_a_decider_and_stored", CARD, [rf(z1, sz, "not_a_decider")], None),
|
||||
sc("a_non_decider_with_a_stale_hash_is_stale_first", CARD, [rf(dict(z1, options_hash=STALE_H), sz, "stale_fork", c=CARD)], None),
|
||||
|
|
@ -306,7 +319,7 @@ scen = [
|
|||
sc("after_every_answer_is_retracted_a_fresh_answer_is_Counted_again", CARD, [X1, ok(RET("n1"), sr("n8"), "Retraction", "n1"), ok(x2, sx2, "Counted", None)], "n2"),
|
||||
]
|
||||
REASON_CODES = ["stale_fork", "not_a_decider", "fork_closed", "choice_invalid", "bad_retraction", "already_retracted"]
|
||||
HTTP = {"unauthenticated": 401, "body_forbidden_field": 400, "body_unknown_field": 400, "body_invalid": 400, "fork_unknown": 404, "insufficient_scope": 403, "forbidden": 403, "request_invalid": 400,
|
||||
HTTP = {"unauthenticated": 401, "body_forbidden_field": 400, "body_unknown_field": 400, "body_invalid": 400, "fork_unknown": 404, "insufficient_scope": 403, "forbidden": 403, "request_id_conflict": 409, "request_invalid": 400,
|
||||
"stale_fork": 409, "not_a_decider": 403, "fork_closed": 409, "choice_invalid": 400, "bad_retraction": 400, "already_retracted": 409}
|
||||
STORED_REFUSALS = []
|
||||
for reason in REASON_CODES:
|
||||
|
|
@ -411,6 +424,8 @@ fork = {
|
|||
"invalid": [dict(bad(n, w, m), messagePackHex=hx(m)) for n, w, m in [
|
||||
("answer_with_neither", "an answer object holds a choice, a note, or both", body(answer={"choice": None, "note": None})),
|
||||
("blank_note", "a blank note is no answer", body(None, " \u00a0 ")),
|
||||
("request_id_missing", "map-mode writes every key; a retry needs the id", {k: v for k, v in x1.items() if k != "request_id"}),
|
||||
("request_id_not_a_uuid", "request_id is a lowercase D-format UUID", dict(x1, request_id="retry-1")),
|
||||
("note_over_4000", "notes are at most 4000 UTF-8 bytes", body(None, "x" * 4001)),
|
||||
("note_multibyte_4001_bytes", "a note is counted in UTF-8 bytes: 1999 e-acute is 3998 bytes, plus three ASCII is 4001 (rule: not expressible in the schema, 2002 characters)", body(None, "\u00e9" * 1999 + "abc")),
|
||||
("note_astral_4004_bytes", "1001 astral characters are 4004 bytes though only 1001 code points (rule: not expressible in the schema)", body(None, "\U0001F600" * 1001)),
|
||||
|
|
|
|||
|
|
@ -296,8 +296,10 @@ namespace GameCult.Networking.Tests
|
|||
["body_unknown_field"] = "the body is a closed shape",
|
||||
["body_invalid"] = "the body does not satisfy gamecult.fork.answer_request.v0",
|
||||
["fork_unknown"] = "no such fork",
|
||||
["forbidden"] = "only Active members may use the desk",
|
||||
["request_id_conflict"] = "this request_id was used for a different body",
|
||||
};
|
||||
private static readonly string[] RequestKeys = { "schemaVersion", "fork_id", "options_hash", "answer", "retracted", "retracts", "answered_at" };
|
||||
private static readonly string[] RequestKeys = { "schemaVersion", "fork_id", "options_hash", "answer", "retracted", "retracts", "answered_at", "request_id" };
|
||||
|
||||
private static bool HasKey(JsonNode? n, params string[] names) => n switch
|
||||
{
|
||||
|
|
@ -312,6 +314,7 @@ namespace GameCult.Networking.Tests
|
|||
var card = startCard;
|
||||
var answers = new JsonArray();
|
||||
var responses = new List<JsonNode?>();
|
||||
var seen = new Dictionary<string, (JsonNode Body, JsonNode Response)>(); // (answerer, request_id) -> the first stored outcome
|
||||
string? Counted()
|
||||
{
|
||||
var hash = HashOf(card);
|
||||
|
|
@ -341,20 +344,27 @@ namespace GameCult.Networking.Tests
|
|||
["options_hash"] = Clone(b["options_hash"]), ["choice"] = Clone(a?["choice"]), ["note"] = Clone(a?["note"]), ["answered_at"] = Clone(b["answered_at"]),
|
||||
["received_at"] = Clone(s["received_at"]),
|
||||
["claim_in_future"] = (DateTimeOffset.Parse(S(b["answered_at"])) - DateTimeOffset.Parse(S(s["received_at"]))).TotalSeconds > 300,
|
||||
["answerer"] = Clone(s["answerer"]), ["authority"] = Clone(s["authority"])
|
||||
["answerer"] = Clone(s["answerer"]), ["authority"] = Clone(s["authority"]), ["request_id"] = Clone(b["request_id"])
|
||||
};
|
||||
answers.Add(Clone(doc));
|
||||
return new JsonObject { ["schemaVersion"] = "gamecult.fork.answer_result.v0", ["answer"] = doc, ["card"] = code == "stale_fork" ? Clone(card) : null };
|
||||
var stored = new JsonObject { ["schemaVersion"] = "gamecult.fork.answer_result.v0", ["answer"] = doc, ["card"] = code == "stale_fork" ? Clone(card) : null };
|
||||
seen[S(s["answerer"]) + "|" + S(b["request_id"])] = (Clone(b)!, Clone(stored)!);
|
||||
return stored;
|
||||
}
|
||||
JsonNode Refuse(string code) => Store("Refused", null, code);
|
||||
var deciders = card["deciders"]!.AsArray().Select(S).ToList();
|
||||
var retracted = b["retracted"] is JsonValue rv && rv.TryGetValue<bool>(out var rb) && rb;
|
||||
var down = s["door_down"] is not null; // the second door failed to answer; "stored" says whether Huginn had the request by then
|
||||
var reached = s["stored"] is not null;
|
||||
JsonNode Unavailable() => new JsonObject { ["schemaVersion"] = "gamecult.fork.unavailable.v0", ["code"] = "unavailable", ["error"] = "unavailable: the outcome is not confirmed, try again with the same request_id", ["retryAfterSeconds"] = Clone(s["retry_after_seconds"]) };
|
||||
JsonNode response;
|
||||
if (s["answerer"] is null) response = Door("unauthenticated");
|
||||
else if (s["active"] is JsonValue activeValue && !activeValue.GetValue<bool>()) response = Door("forbidden");
|
||||
else if (HasKey(b, "answerer", "authority")) response = Door("body_forbidden_field");
|
||||
else if (b.Any(kv => !RequestKeys.Contains(kv.Key)) || (b["answer"] is JsonObject ao && ao.Any(kv => kv.Key is not ("choice" or "note")))) response = Door("body_unknown_field");
|
||||
else if (Errors(ForkSchema, "answerRequest", b).Count > 0 || NoteRuleErrors("answerRequest", b).Any() || (!retracted && b["answer"] is null)) response = Door("body_invalid");
|
||||
else if (s["door_down"] is not null) response = new JsonObject { ["schemaVersion"] = "gamecult.fork.unavailable.v0", ["code"] = "unavailable", ["error"] = "unavailable: the answer path is down, try again", ["retryAfterSeconds"] = Clone(s["retry_after_seconds"]) };
|
||||
else if (down && !reached) response = Unavailable();
|
||||
else if (seen.TryGetValue(S(s["answerer"]) + "|" + S(b["request_id"]), out var prior)) response = JsonNode.DeepEquals(prior.Body, b) ? Clone(prior.Response)! : Door("request_id_conflict");
|
||||
else if (S(b["fork_id"]) != S(card["fork_id"])) response = Door("fork_unknown");
|
||||
else if (S(b["options_hash"]) != HashOf(card)) response = Refuse("stale_fork");
|
||||
else if (!deciders.Contains(S(s["answerer"]))) response = Refuse("not_a_decider");
|
||||
|
|
@ -373,7 +383,7 @@ namespace GameCult.Networking.Tests
|
|||
var first = Counted();
|
||||
response = first is null ? Store("Counted", null, null) : Store("Revision", first, null);
|
||||
}
|
||||
responses.Add(response);
|
||||
responses.Add(down && reached ? Unavailable() : response);
|
||||
}
|
||||
var record = new JsonObject
|
||||
{
|
||||
|
|
@ -387,7 +397,7 @@ namespace GameCult.Networking.Tests
|
|||
{
|
||||
var seen = new HashSet<string>();
|
||||
var doorRefusals = 0;
|
||||
var door = new HashSet<string> { "unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "unavailable" };
|
||||
var door = new HashSet<string> { "unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "forbidden", "request_id_conflict" };
|
||||
foreach (var sc in Fork["scenarios"]!.AsArray())
|
||||
{
|
||||
var name = S(sc!["name"]);
|
||||
|
|
@ -409,6 +419,9 @@ namespace GameCult.Networking.Tests
|
|||
if (r["code"] is not null)
|
||||
{
|
||||
seen.Add(S(r["code"]));
|
||||
// unavailable promises nothing: the outcome is not confirmed, so the answer is stored exactly when Huginn had it
|
||||
if (S(r["code"]) == "unavailable")
|
||||
Assert.That(sc["record"]!["answers"]!.AsArray().Any(a => S(a!["answer_id"]) == S(step["server"]!["answer_id"])), Is.EqualTo(step["server"]!["stored"] is not null), $"{name} unavailable");
|
||||
if (door.Contains(S(r["code"])))
|
||||
{
|
||||
doorRefusals++;
|
||||
|
|
@ -420,7 +433,7 @@ namespace GameCult.Networking.Tests
|
|||
foreach (var a in sc["record"]!["answers"]!.AsArray()) seen.Add(S(a!["outcome"]));
|
||||
}
|
||||
Assert.That(doorRefusals, Is.GreaterThanOrEqualTo(8));
|
||||
foreach (var want in new[] { "Counted", "Revision", "Retraction", "Refused", "unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "unavailable", "stale_fork",
|
||||
foreach (var want in new[] { "Counted", "Revision", "Retraction", "Refused", "unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "unavailable", "forbidden", "request_id_conflict", "stale_fork",
|
||||
"not_a_decider", "fork_closed", "choice_invalid", "bad_retraction", "already_retracted" })
|
||||
Assert.That(seen, Does.Contain(want));
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue