Public: anyone can read this; the crew can change it.
The client list shows when each forge link was last opened, or that it has not been #13218
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/13137-the-client-list-shows-when-each-forge-li → main 4 commits fork 3 threads · 3 unresolved
4 files
changed +72
−16
src/contract/openapi/routes/getApiV1Forge.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/forge", summary: "A spawned forge's word about itself: { claimed, lastActivityAt, link? }; lastActivityAt, link ({ state, revokedAt, usedAt }) are null or absent, as is madeFrom ({ template, at }), unless the parent's secret is sent", auth: false, role: "anonymous", refusals: { not_found: "404: this forge was not spawned" } }; | |
| 3 | export const route: Route = { method: "get", path: "/api/v1/forge", summary: "A spawned forge's word about itself: { claimed, lastActivityAt, link? }; lastActivityAt, link ({ state, revokedAt, usedAt, openedAt, lastOpenedAt }) are null or absent, as is madeFrom ({ template, at }), unless the parent's secret is sent", auth: false, role: "anonymous", refusals: { not_found: "404: this forge was not spawned" } }; |
src/spawn/claim.ts +16 −8
| @@ -56,6 +56,8 @@ interface Stored { | ||
| 56 | 56 | readonly r?: string; |
| 57 | 57 | /** When a browser first opened the claim page, ISO; absent until one did. */ |
| 58 | 58 | readonly o?: string; |
| 59 | /** When a browser last opened the claim page, ISO; absent until one did. */ | |
| 60 | readonly l?: string; | |
| 59 | 61 | } |
| 60 | 62 | |
| 61 | 63 | export type ClaimState = |
| @@ -388,8 +390,8 @@ export function becomeOrg( | ||
| 388 | 390 | db.query("DELETE FROM session WHERE user_id = ?1").run(orgId); |
| 389 | 391 | if (input.credential !== undefined && !addPasskey(db, orgId, "Passkey", input.credential).ok) throw new PasskeyRefused(); |
| 390 | 392 | // The one-time claim link is the proof, as it is for an account made beside the organisation |
| 391 | // (`createUser` with `trusted`). An organisation needed no proof; the person it becomes does, or | |
| 392 | // the crew answers their first ask with "Verify your email first." | |
| 393 | // (`createUser` with `trusted`). An organisation needed no proof; the person it becomes does, | |
| 394 | // or the crew answers their first ask with "Verify your email first." | |
| 393 | 395 | markVerified(db, orgId, new Date().toISOString()); |
| 394 | 396 | return true; |
| 395 | 397 | }); |
| @@ -431,11 +433,15 @@ export interface LinkInfo { | ||
| 431 | 433 | readonly usedAt?: string | null; |
| 432 | 434 | /** When a person's browser first opened the claim page, ISO; null while none did. */ |
| 433 | 435 | readonly openedAt?: string | null; |
| 436 | /** When a person's browser last opened the claim page, ISO; null while none did. */ | |
| 437 | readonly lastOpenedAt?: string | null; | |
| 434 | 438 | /** When the link stops working, ISO. */ |
| 435 | 439 | readonly expiresAt?: string; |
| 436 | 440 | } |
| 437 | 441 | |
| 438 | /** True while an ended link can still be brought back: revoked in the last minute, in date, unspent. */ | |
| 442 | /** | |
| 443 | * True while an ended link can still be brought back: revoked in the last minute, in date, unspent. | |
| 444 | */ | |
| 439 | 445 | export const undoable = (link: LinkInfo, now = Date.now()): boolean => |
| 440 | 446 | link.state === "ended" && link.revokedAt !== null && now - Date.parse(link.revokedAt) <= REVOKE_UNDO_MS; |
| 441 | 447 | |
| @@ -460,7 +466,7 @@ const stateOf = (s: Stored, now: number): LinkState => | ||
| 460 | 466 | /** The claim link in this forge's own database; null when it has none. */ |
| 461 | 467 | export function linkOf(db: Database, now = Date.now()): LinkInfo | null { |
| 462 | 468 | const found = readStored(db); |
| 463 | return found === undefined ? null : { state: stateOf(found.stored, now), revokedAt: found.stored.r ?? null, usedAt: found.stored.u, openedAt: found.stored.o ?? null, expiresAt: found.stored.e }; | |
| 469 | return found === undefined ? null : { state: stateOf(found.stored, now), revokedAt: found.stored.r ?? null, usedAt: found.stored.u, openedAt: found.stored.o ?? null, lastOpenedAt: found.stored.l ?? found.stored.o ?? null, expiresAt: found.stored.e }; | |
| 464 | 470 | } |
| 465 | 471 | |
| 466 | 472 | /** Replace the stored link only if nobody changed it since it was read. */ |
| @@ -487,14 +493,16 @@ export function isBrowserOpen(req: Request): boolean { | ||
| 487 | 493 | } |
| 488 | 494 | |
| 489 | 495 | /** |
| 490 | * Remember the first time the open link's page was opened; false when it was not open or | |
| 491 | * already noted. | |
| 496 | * Remember that the open link's page was opened: the first open sets the first and the last | |
| 497 | * time, each later one moves the last time only. One write per open; no address, no agent | |
| 498 | * string. False when the link was not open. | |
| 492 | 499 | */ |
| 493 | 500 | export function noteOpened(db: Database, now = Date.now()): boolean { |
| 494 | 501 | const row = db.query<{ user_id: string }, [string]>("SELECT user_id FROM user_setting WHERE key = ?1").get(KEY); |
| 495 | 502 | const found = readStored(db); |
| 496 | if (row === null || found === undefined || found.stored.o !== undefined || stateOf(found.stored, now) !== "open") return false; | |
| 497 | return swap(db, row.user_id, found, { ...found.stored, o: new Date(now).toISOString() }); | |
| 503 | if (row === null || found === undefined || stateOf(found.stored, now) !== "open") return false; | |
| 504 | const at = new Date(now).toISOString(); | |
| 505 | return swap(db, row.user_id, found, { ...found.stored, o: found.stored.o ?? at, l: at }); | |
| 498 | 506 | } |
| 499 | 507 | |
| 500 | 508 | /** Take back an open link: from now it answers "ended". False when it was not open. */ |
src/spawn/clients.ts +11 −5
| @@ -223,12 +223,12 @@ export async function forgeState( | ||
| 223 | 223 | const LINK_STATES: readonly LinkState[] = ["open", "used", "ended"]; |
| 224 | 224 | |
| 225 | 225 | /** The link a child reported, or null when it said nothing usable. */ |
| 226 | function linkOfBody(v: unknown): LinkInfo | null { | |
| 226 | export function linkOfBody(v: unknown): LinkInfo | null { | |
| 227 | 227 | if (typeof v !== "object" || v === null) return null; |
| 228 | 228 | const { state, revokedAt } = v as Record<string, unknown>; |
| 229 | 229 | if (!LINK_STATES.includes(state as LinkState)) return null; |
| 230 | 230 | const iso = (x: unknown): string | null => (typeof x === "string" && !Number.isNaN(Date.parse(x)) ? x : null); |
| 231 | return { state: state as LinkState, revokedAt: iso(revokedAt), usedAt: iso((v as Record<string, unknown>)["usedAt"]), openedAt: iso((v as Record<string, unknown>)["openedAt"]) }; | |
| 231 | return { state: state as LinkState, revokedAt: iso(revokedAt), usedAt: iso((v as Record<string, unknown>)["usedAt"]), openedAt: iso((v as Record<string, unknown>)["openedAt"]), lastOpenedAt: iso((v as Record<string, unknown>)["lastOpenedAt"]) }; | |
| 232 | 232 | } |
| 233 | 233 | |
| 234 | 234 | async function probe(app: App, child: Child): Promise<ForgeState | undefined> { |
| @@ -598,8 +598,13 @@ export interface Seen { | ||
| 598 | 598 | readonly sentAt: string | null; |
| 599 | 599 | /** True once a browser opened the page or the link was spent. */ |
| 600 | 600 | readonly opened: boolean; |
| 601 | /** ISO of the first browser open; null while unopened, or spent before opens were noted. */ | |
| 601 | /** | |
| 602 | * ISO of the last browser open (the first when it was opened once); null while unopened, or spent | |
| 603 | * before opens were noted. | |
| 604 | */ | |
| 602 | 605 | readonly openedAt: string | null; |
| 606 | /** ISO of the first browser open; null while unopened, or spent before opens were noted. */ | |
| 607 | readonly firstOpenedAt: string | null; | |
| 603 | 608 | /** ISO of a person's last action there; null until they signed in. */ |
| 604 | 609 | readonly lastSeenAt: string | null; |
| 605 | 610 | } |
| @@ -607,8 +612,9 @@ export interface Seen { | ||
| 607 | 612 | /** Null while the forge is still being made or did not answer: nothing is claimed unknown. */ |
| 608 | 613 | export function seenOf(r: Pick<ClientRow, "made" | "claimed" | "sentAt" | "link" | "lastActivityAt">): Seen | null { |
| 609 | 614 | if (!r.made || r.claimed === null || r.link === null) return null; |
| 610 | const openedAt = r.link.openedAt ?? null; | |
| 611 | return { sentAt: r.sentAt, opened: openedAt !== null || r.link.usedAt != null || r.link.state === "used", openedAt, lastSeenAt: r.claimed ? r.lastActivityAt : null }; | |
| 615 | const firstOpenedAt = r.link.openedAt ?? null; | |
| 616 | const openedAt = r.link.lastOpenedAt ?? firstOpenedAt; | |
| 617 | return { sentAt: r.sentAt, firstOpenedAt, opened: openedAt !== null || r.link.usedAt != null || r.link.state === "used", openedAt, lastSeenAt: r.claimed ? r.lastActivityAt : null }; | |
| 612 | 618 | } |
| 613 | 619 | |
| 614 | 620 | /** The one line as parts to join with " · ": the words, and the instant to say beside them. */ |
test/client-link-seen.test.ts +44 −2
| @@ -12,8 +12,8 @@ import { createApp, type App } from "../src/app.ts"; | ||
| 12 | 12 | import { createUser } from "../src/core/users.ts"; |
| 13 | 13 | import { createOrg } from "../src/core/orgs.ts"; |
| 14 | 14 | import { serve, type Servers } from "../src/http/server.ts"; |
| 15 | import { isBrowserOpen, linkOf, mintClaim } from "../src/spawn/claim.ts"; | |
| 16 | import { seenOf, type ClientRow } from "../src/spawn/clients.ts"; | |
| 15 | import { isBrowserOpen, linkOf, mintClaim, noteOpened } from "../src/spawn/claim.ts"; | |
| 16 | import { linkOfBody, seenOf, type ClientRow } from "../src/spawn/clients.ts"; | |
| 17 | 17 | import { forgeLines } from "../src/tui/screens/forges.ts"; |
| 18 | 18 | import { forgeRow } from "../src/web/pages/forges.ts"; |
| 19 | 19 | import { quietLogs } from "./helpers/globals.ts"; |
| @@ -86,6 +86,20 @@ describe("the client list says whether the link was looked at", () => { | ||
| 86 | 86 | }); |
| 87 | 87 | }); |
| 88 | 88 | |
| 89 | describe("the parent reads the child's word", () => { | |
| 90 | test("lastOpenedAt crosses the wire and the row says it", () => { | |
| 91 | const body = JSON.parse(JSON.stringify({ state: "open", revokedAt: null, usedAt: null, openedAt: ago(2 * DAY), lastOpenedAt: ago(DAY) })); | |
| 92 | const link = linkOfBody(body)!; | |
| 93 | expect(link.lastOpenedAt).toBe(body.lastOpenedAt); | |
| 94 | expect(html(row({ link }))).toContain("opened 1d ago"); | |
| 95 | }); | |
| 96 | ||
| 97 | test("a child that sends no or a bad lastOpenedAt yields null", () => { | |
| 98 | expect(linkOfBody({ state: "open", openedAt: ago(DAY) })!.lastOpenedAt).toBeNull(); | |
| 99 | expect(linkOfBody({ state: "open", lastOpenedAt: "nope" })!.lastOpenedAt).toBeNull(); | |
| 100 | }); | |
| 101 | }); | |
| 102 | ||
| 89 | 103 | describe("only a person's browser counts as opening", () => { |
| 90 | 104 | const get = (headers: Record<string, string>, method = "GET") => new Request("https://x.test/claim", { method, headers }); |
| 91 | 105 | const html5 = { accept: "text/html,application/xhtml+xml;q=0.9,*/*;q=0.8" }; |
| @@ -137,6 +151,34 @@ describe("only a person's browser counts as opening", () => { | ||
| 137 | 151 | expect(linkOf(app.db)!.openedAt).toBe(first); |
| 138 | 152 | }); |
| 139 | 153 | |
| 154 | test("a later open moves the last-opened time and keeps the first; one write each, nothing about the visitor", () => { | |
outdated
This test builds the row by hand, so it never covers the child to parent wire. Add the wire case, and one for a legacy link with no |
||
| 155 | mintClaim(app.db, orgId); | |
| 156 | expect(noteOpened(app.db, NOW)).toBe(true); | |
| 157 | expect(noteOpened(app.db, NOW + DAY)).toBe(true); | |
| 158 | const link = linkOf(app.db)!; | |
| 159 | expect(link.openedAt).toBe(new Date(NOW).toISOString()); | |
| 160 | expect(link.lastOpenedAt).toBe(new Date(NOW + DAY).toISOString()); | |
| 161 | const stored = app.db.query<{ value: string }, []>("SELECT value FROM user_setting WHERE key = 'spawn_claim'").get()!.value; | |
| 162 | expect(Object.keys(JSON.parse(stored)).sort()).toEqual(["e", "h", "l", "o", "u"]); | |
| 163 | expect(noteOpened(app.db, NOW + 400 * DAY)).toBe(false); | |
| 164 | }); | |
| 165 | ||
| 166 | test("the list says when the link was last opened", () => { | |
| 167 | const h = html(row({ link: { state: "open", revokedAt: null, usedAt: null, openedAt: ago(2 * DAY), lastOpenedAt: ago(DAY) } })); | |
| 168 | expect(h).toContain("sent 3d ago · opened 1d ago"); | |
| 169 | }); | |
| 170 | ||
| 171 | test("a link opened before last-opened was kept reads its first open as the last", () => { | |
| 172 | mintClaim(app.db, orgId); | |
| 173 | noteOpened(app.db, NOW); | |
| 174 | const stored = app.db.query<{ value: string }, []>("SELECT value FROM user_setting WHERE key = 'spawn_claim'").get()!.value; | |
| 175 | const { l: _l, ...legacy } = JSON.parse(stored); | |
| 176 | app.db.query("UPDATE user_setting SET value = ?1 WHERE key = 'spawn_claim'").run(JSON.stringify(legacy)); | |
| 177 | const link = linkOf(app.db)!; | |
| 178 | expect(link.openedAt).toBe(new Date(NOW).toISOString()); | |
| 179 | expect(link.lastOpenedAt).toBe(link.openedAt); | |
| 180 | }); | |
| 181 | ||
| 140 | 182 | test("the child's own link page (/welcome) notes no open and its pages never say it", async () => { |
| 141 | 183 | // Reset: a new link, unopened. |
| 142 | 184 | mintClaim(app.db, orgId); |
new above
offline
Non-blocking: firstOpenedAt has no reader in this change. It is dead until the stage logic uses it; drop it or use it.