@mostra/runtime 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/dist/bin.js +930 -458
  2. package/dist/bin.js.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/{instance-DCiUHvgZ.js → instance-D5gh-sMM.js} +1231 -46
  5. package/dist/instance-D5gh-sMM.js.map +1 -0
  6. package/dist/reference/cli.md +112 -2
  7. package/dist/reference/diagnostics.json +29 -2
  8. package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +2 -2
  9. package/dist/reference/errors/MOSTRA_TEAM_PRESENCE_RATE_LIMITED.md +23 -0
  10. package/dist/reference/errors/MOSTRA_TEAM_ROSTER_POLICY.md +23 -0
  11. package/dist/reference/errors/MOSTRA_TEAM_ROSTER_TOO_LARGE.md +23 -0
  12. package/dist/reference/self-hosting.md +1 -1
  13. package/dist/skill/SKILL.md +5 -3
  14. package/dist/skill/references/answers.md +3 -1
  15. package/dist/skill/references/mcp.md +2 -2
  16. package/dist/skill/references/teams.md +78 -0
  17. package/package.json +6 -6
  18. package/src/actions/index.ts +5 -2
  19. package/src/gateway/actions.ts +6 -1
  20. package/src/gateway/browser.ts +84 -1
  21. package/src/gateway/capabilities.ts +5 -1
  22. package/src/gateway/index.ts +43 -1
  23. package/src/gateway/team.ts +181 -0
  24. package/src/instance/index.ts +2 -1
  25. package/src/interaction/ephemeral.ts +21 -0
  26. package/src/interaction/events.ts +17 -0
  27. package/src/interaction/index.ts +265 -20
  28. package/src/interaction/roster.ts +585 -0
  29. package/src/interaction/team.ts +426 -0
  30. package/src/interaction/wait.ts +150 -0
  31. package/src/ledger/migrations.ts +44 -0
  32. package/src/link/hosted.ts +14 -3
  33. package/src/link/manager.ts +31 -1
  34. package/src/server/api.ts +1 -1
  35. package/src/server/auth.ts +83 -16
  36. package/src/server/authorize.ts +27 -4
  37. package/src/server/config.ts +53 -0
  38. package/src/server/directory.ts +73 -0
  39. package/src/server/feed.ts +89 -3
  40. package/src/server/hosted-pages.ts +19 -6
  41. package/src/server/hosted.ts +108 -49
  42. package/src/server/index.ts +72 -15
  43. package/src/server/metering.ts +117 -12
  44. package/src/server/operator.ts +87 -28
  45. package/src/server/providers.ts +61 -9
  46. package/src/server/relay.ts +258 -107
  47. package/src/share/index.ts +50 -2
  48. package/src/verify/index.ts +7 -0
  49. package/src/verify/runner.ts +5 -1
  50. package/dist/instance-DCiUHvgZ.js.map +0 -1
@@ -152,19 +152,32 @@ export function hostedPages(
152
152
  });
153
153
  };
154
154
 
155
- /** A link past the operator's longest lifetime or idle limit: revoked now, 410 (D165 item 9). */
156
- const expired = (tokenId: string, policy: LinkPolicy): Refusal | undefined => {
155
+ /**
156
+ * A link past the operator's longest lifetime or idle limit: revoked now, 410 (D165 item 9).
157
+ * "Idle" is as `LinkPolicy.idleExpiry` says, without a view: the link's last use before this
158
+ * visit is the later of its last view (a frame ticket) and the activity of its other sessions
159
+ * (`last_seen_at`, which a page's every request keeps, so a page open and in use for longer
160
+ * than the idle time keeps its link). The session asking for this ticket is left out, since its
161
+ * own exchange, or any request of a returning browser, has just written it: counted, an idle
162
+ * link would open for every new visit (MT-03, and its Opus review). A session's activity is
163
+ * written at most every `touchMs` (an hour), so a link lapses at most that much early.
164
+ */
165
+ const expired = (tokenId: string, asking: string, policy: LinkPolicy): Refusal | undefined => {
157
166
  if (policy.maxTtl === undefined && policy.idleExpiry === undefined) return undefined;
158
167
  const used = ledger.read((db) =>
159
- db.get<{ created_at: string; last: string | null }>(
160
- `SELECT t.created_at, (SELECT MAX(last_seen_at) FROM session s WHERE s.token_id = t.id) AS last
168
+ db.get<{ created_at: string; viewed: string | null; active: string | null }>(
169
+ `SELECT t.created_at,
170
+ (SELECT MAX(v.opened_at) FROM view v WHERE v.token_id = t.id) AS viewed,
171
+ (SELECT MAX(s.last_seen_at) FROM session s WHERE s.token_id = t.id AND s.id != ?) AS active
161
172
  FROM token t WHERE t.id = ?`,
173
+ asking,
162
174
  tokenId,
163
175
  ),
164
176
  );
165
177
  if (!used) return undefined;
166
178
  const minted = Date.parse(used.created_at);
167
- const lastUse = Math.max(minted, used.last === null ? 0 : Date.parse(used.last));
179
+ const at = (value: string | null): number => (value === null ? 0 : Date.parse(value));
180
+ const lastUse = Math.max(minted, at(used.viewed), at(used.active));
168
181
  const tooOld = policy.maxTtl !== undefined && now() - minted > durationMs(policy.maxTtl);
169
182
  const idle = policy.idleExpiry !== undefined && now() - lastUse > durationMs(policy.idleExpiry);
170
183
  if (!tooOld && !idle) return undefined;
@@ -411,7 +424,7 @@ export function hostedPages(
411
424
  async admitView(input) {
412
425
  if (quarantineOf(input.artifactId, input.versionId) !== undefined) return underReview();
413
426
  const policy = await policyFor(input.artifactId, input.tokenId);
414
- const gone = expired(input.tokenId, policy);
427
+ const gone = expired(input.tokenId, input.sessionId, policy);
415
428
  if (gone) return gone;
416
429
  const route = options.routeOf(input.artifactId);
417
430
  // `view` proceeds when the operator doesn't answer: nothing a person sees is held up by it.
@@ -45,7 +45,7 @@ import {
45
45
  } from "../gateway/index.ts";
46
46
  import { platformName } from "../home/index.ts";
47
47
  import { createEphemeralBus, createInteraction, type Interaction } from "../interaction/index.ts";
48
- import type { Ledger } from "../ledger/index.ts";
48
+ import type { Ledger, LedgerDb } from "../ledger/index.ts";
49
49
  import { createLive, liveMethods } from "../live/index.ts";
50
50
  import type { Log } from "../log.ts";
51
51
  import { removeTree } from "../platform/index.ts";
@@ -114,7 +114,7 @@ export interface HostedHome {
114
114
  */
115
115
  wanted(sha256: string): number | undefined;
116
116
  /** Records a file this home uploaded (`PUT /files/<sha256>`, §18.2). */
117
- uploaded(sha256: string): void;
117
+ uploaded(sha256: string, size: number): void;
118
118
  /** Pauses or resumes an artifact as its owner or the operator (D165 item 14). */
119
119
  pause(
120
120
  artifactId: string,
@@ -128,6 +128,13 @@ export interface HostedHome {
128
128
  revokeLinks(artifactId: string): number;
129
129
  /** Revokes one link; `false` when this home has no such link. */
130
130
  revokeLink(tokenId: string): boolean;
131
+ /**
132
+ * A personal link's URL and expiry, built from its token now (an invitation's, D168), or
133
+ * `undefined` when it no longer works: revoked, expired, or made where it can't be shown again.
134
+ */
135
+ invitationLink(
136
+ tokenId: string,
137
+ ): { readonly url: string; readonly expiresAt?: string } | undefined;
131
138
  /**
132
139
  * Removes an artifact and everything of it from this home (`ServerHandle.remove`): its rows, its
133
140
  * version files no other version of the home names, and its route; its label is kept issued
@@ -176,6 +183,8 @@ export interface HostedHomeOptions {
176
183
  /** The relay's server settings (`relay` in the configuration, D165 item 4). */
177
184
  /** The test fault points (`MOSTRA_TEST_FAULTS`); none by default. */
178
185
  readonly faults?: Faults;
186
+ /** How often a session's activity is written at most (tests shorten it; an hour by default). */
187
+ readonly sessionTouchMs?: number | undefined;
179
188
  readonly relay?: {
180
189
  readonly waitingRunsPerArtifact?: number | undefined;
181
190
  readonly drainPerSecond?: number | undefined;
@@ -248,6 +257,12 @@ export async function openHostedHome(options: HostedHomeOptions): Promise<Hosted
248
257
  const interaction = createInteraction({
249
258
  // A respondent on a hosted link learns only that the answer was sent (D165 item 1a).
250
259
  sentOnly: true,
260
+ // The owner is the account the home belongs to, signed in on its page (CO-07): it sees every
261
+ // respondent and every present viewer, whatever the artifact's visibility.
262
+ isOwner: (viewer) =>
263
+ options.services !== undefined &&
264
+ viewer.kind === "account" &&
265
+ viewer.ref === options.services.owner(id).account,
251
266
  ledger,
252
267
  log,
253
268
  faults: noFaults,
@@ -367,6 +382,7 @@ export async function openHostedHome(options: HostedHomeOptions): Promise<Hosted
367
382
  now: () => Date.now(),
368
383
  shellOrigin: () => originOf(options.domains.active),
369
384
  servesShell,
385
+ ...(options.sessionTouchMs !== undefined ? { touchIntervalMs: options.sessionTouchMs } : {}),
370
386
  // Every hosted link is indexed in the directory, so the operator's `revokeLink` finds its home.
371
387
  onMinted: ({ tokenId, artifactId }) => {
372
388
  const route = routeOf(artifactId);
@@ -443,6 +459,23 @@ export async function openHostedHome(options: HostedHomeOptions): Promise<Hosted
443
459
  ...(options.relay?.sweepMs !== undefined ? { sweepMs: options.relay.sweepMs } : {}),
444
460
  ...(options.relay?.liveRenewMs !== undefined ? { liveRenewMs: options.relay.liveRenewMs } : {}),
445
461
  ...(options.relay?.perLink !== undefined ? { perLink: options.relay.perLink } : {}),
462
+ // The operator's `limits` for a page's relayed actions (D165 item 9), each with quantity 1.
463
+ ...(options.services
464
+ ? {
465
+ limit: (artifactId: string, operation: "run" | "run.wait" | "call") => {
466
+ const services = options.services as HostedServices;
467
+ const route = routeOf(artifactId);
468
+ return services.operator.limit({
469
+ account: services.owner(id).account,
470
+ home: id,
471
+ artifact: artifactId,
472
+ ...(route ? { routeId: route.id } : {}),
473
+ operation,
474
+ quantity: 1,
475
+ });
476
+ },
477
+ }
478
+ : {}),
446
479
  latestVersion: (artifactId) =>
447
480
  ledger.read(
448
481
  (db) =>
@@ -477,6 +510,8 @@ export async function openHostedHome(options: HostedHomeOptions): Promise<Hosted
477
510
  shellDir: options.shellDir,
478
511
  interaction,
479
512
  bus,
513
+ // `roster/add` asks the operator's `limits` for the personal links it mints (D168).
514
+ linkLimit: (artifactId, count) => linkLimit(artifactId, count),
480
515
  actions: relay,
481
516
  live: hostedLive,
482
517
  // Both channels: a hosted home has no host to narrow them (its owner is a host of it, D165).
@@ -618,6 +653,33 @@ export async function openHostedHome(options: HostedHomeOptions): Promise<Hosted
618
653
  if (!gateway.dispatch(key, request, response)) notServed(response);
619
654
  };
620
655
 
656
+ /**
657
+ * Records that this home holds a version file (DATA_MODEL §7.1's `home_file`), counted once in
658
+ * `file_ref`, with its size in bytes (the size its push gave, held to the bytes), which metering's
659
+ * `bytes.held` sums (MT-03). A row recorded before sizes were kept takes it now.
660
+ */
661
+ const holdFile = (db: LedgerDb, sha: string, size: number | undefined): void => {
662
+ const added = db.run(
663
+ "INSERT OR IGNORE INTO home_file (home_id, sha256, size) VALUES (?, ?, ?)",
664
+ id,
665
+ sha,
666
+ size ?? null,
667
+ );
668
+ if (added.changes > 0) {
669
+ db.run(
670
+ "INSERT INTO file_ref (sha256, homes) VALUES (?, 1) ON CONFLICT (sha256) DO UPDATE SET homes = homes + 1, unreferenced_at = NULL",
671
+ sha,
672
+ );
673
+ } else if (size !== undefined) {
674
+ db.run(
675
+ "UPDATE home_file SET size = ? WHERE home_id = ? AND sha256 = ? AND size IS NULL",
676
+ size,
677
+ id,
678
+ sha,
679
+ );
680
+ }
681
+ };
682
+
621
683
  /** The client files of a listing this home doesn't hold yet. */
622
684
  const missingOf = (files: readonly string[]): string[] =>
623
685
  directory.read((db) =>
@@ -646,32 +708,35 @@ export async function openHostedHome(options: HostedHomeOptions): Promise<Hosted
646
708
  };
647
709
 
648
710
  /**
649
- * `view/url` on a hosted home under the operator's `limits` (`link`): refused with its words, and
650
- * refused for now when the operator doesn't answer, since a link creates something (D165 item 9).
711
+ * New links on a hosted home under the operator's `limits` (`link`): `view/url`'s one, and the
712
+ * personal links `roster/add` mints (D168); refused with the operator's words, and refused for now
713
+ * when it doesn't answer, since a link creates something (D165 item 9).
651
714
  */
715
+ const linkLimit = async (artifactId: string, quantity?: number): Promise<void> => {
716
+ const services = options.services;
717
+ if (!services) return;
718
+ const route = routeOf(artifactId);
719
+ const verdict = await services.operator.limit({
720
+ account: services.owner(id).account,
721
+ home: id,
722
+ artifact: artifactId,
723
+ ...(route ? { routeId: route.id } : {}),
724
+ operation: "link",
725
+ ...(quantity !== undefined ? { quantity } : {}),
726
+ });
727
+ if (verdict.allowed === "unavailable") {
728
+ throw refuse(
729
+ "MOSTRA_REMOTE_OPERATOR_UNAVAILABLE",
730
+ "The server's operator didn't answer in time; try minting the link again.",
731
+ );
732
+ }
733
+ if (verdict.allowed === false) throw refuse("MOSTRA_REMOTE_LIMIT_REACHED", verdict.message);
734
+ };
652
735
  const limitedLinks = (method: MethodHandler): MethodHandler => ({
653
736
  definition: method.definition,
654
737
  async handle(params, session) {
655
- const services = options.services;
656
- if (services) {
657
- const ref = (params as { artifact?: unknown }).artifact;
658
- const artifactId = registry.get(canonicalRef(ref as never)).id;
659
- const route = routeOf(artifactId);
660
- const verdict = await services.operator.limit({
661
- account: services.owner(id).account,
662
- home: id,
663
- artifact: artifactId,
664
- ...(route ? { routeId: route.id } : {}),
665
- operation: "link",
666
- });
667
- if (verdict.allowed === "unavailable") {
668
- throw refuse(
669
- "MOSTRA_REMOTE_OPERATOR_UNAVAILABLE",
670
- "The server's operator didn't answer in time; try minting the link again.",
671
- );
672
- }
673
- if (verdict.allowed === false) throw refuse("MOSTRA_REMOTE_LIMIT_REACHED", verdict.message);
674
- }
738
+ const ref = (params as { artifact?: unknown }).artifact;
739
+ await linkLimit(registry.get(canonicalRef(ref as never)).id);
675
740
  return method.handle(params, session);
676
741
  },
677
742
  });
@@ -850,6 +915,8 @@ export async function openHostedHome(options: HostedHomeOptions): Promise<Hosted
850
915
  home: id,
851
916
  artifact: params.artifactId,
852
917
  routeId: route.routeId,
918
+ // The version itself, so a push that takes several rounds is one version (MT-03).
919
+ versionId: version.versionId,
853
920
  operation,
854
921
  quantity,
855
922
  });
@@ -921,17 +988,7 @@ export async function openHostedHome(options: HostedHomeOptions): Promise<Hosted
921
988
  });
922
989
  directory.write((db) => {
923
990
  for (const sha of new Set(clientFiles.map(([, , file]) => file))) {
924
- const added = db.run(
925
- "INSERT OR IGNORE INTO home_file (home_id, sha256) VALUES (?, ?)",
926
- id,
927
- sha,
928
- );
929
- if (added.changes > 0) {
930
- db.run(
931
- "INSERT INTO file_ref (sha256, homes) VALUES (?, 1) ON CONFLICT (sha256) DO UPDATE SET homes = homes + 1, unreferenced_at = NULL",
932
- sha,
933
- );
934
- }
991
+ holdFile(db, sha, sizes.get(sha));
935
992
  }
936
993
  });
937
994
  log.info("server.version_pushed", {
@@ -1119,6 +1176,13 @@ export async function openHostedHome(options: HostedHomeOptions): Promise<Hosted
1119
1176
  operator: options.services.operator,
1120
1177
  meter: options.services.meter,
1121
1178
  account: () => (options.services as HostedServices).owner(id).account,
1179
+ sender: () => {
1180
+ const owner = (options.services as HostedServices).owner(id);
1181
+ return {
1182
+ ...(owner.name !== undefined ? { name: owner.name } : {}),
1183
+ ...(owner.verifiedBy !== undefined ? { verifiedBy: owner.verifiedBy } : {}),
1184
+ };
1185
+ },
1122
1186
  routeOf,
1123
1187
  incarnation: () => incarnation,
1124
1188
  log,
@@ -1140,20 +1204,8 @@ export async function openHostedHome(options: HostedHomeOptions): Promise<Hosted
1140
1204
  }
1141
1205
  return undefined;
1142
1206
  },
1143
- uploaded(sha) {
1144
- directory.write((db) => {
1145
- const added = db.run(
1146
- "INSERT OR IGNORE INTO home_file (home_id, sha256) VALUES (?, ?)",
1147
- id,
1148
- sha,
1149
- );
1150
- if (added.changes > 0) {
1151
- db.run(
1152
- "INSERT INTO file_ref (sha256, homes) VALUES (?, 1) ON CONFLICT (sha256) DO UPDATE SET homes = homes + 1, unreferenced_at = NULL",
1153
- sha,
1154
- );
1155
- }
1156
- });
1207
+ uploaded(sha, size) {
1208
+ directory.write((db) => holdFile(db, sha, size));
1157
1209
  for (const files of pending.values()) files.delete(sha);
1158
1210
  },
1159
1211
  pause: (artifactId, change) => interaction.pause(artifactId, change),
@@ -1170,6 +1222,13 @@ export async function openHostedHome(options: HostedHomeOptions): Promise<Hosted
1170
1222
  },
1171
1223
  revokeLinks,
1172
1224
  revokeLink: (tokenId) => capabilities.revoke(tokenId) !== "unknown",
1225
+ invitationLink(tokenId) {
1226
+ const grant = capabilities.grant(tokenId);
1227
+ if (!grant?.live) return undefined;
1228
+ const url = gateway.reveal(tokenId);
1229
+ if (url === undefined) return undefined;
1230
+ return { url, ...(grant.expiresAt !== undefined ? { expiresAt: grant.expiresAt } : {}) };
1231
+ },
1173
1232
  async remove(artifactId) {
1174
1233
  /** The client files a version's listing names. */
1175
1234
  const clientFilesOf = async (versionId: string): Promise<string[]> => {
@@ -12,7 +12,7 @@
12
12
  * ```
13
13
  */
14
14
 
15
- import { readFileSync } from "node:fs";
15
+ import { readFileSync, statSync } from "node:fs";
16
16
  import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
17
17
  import type { AddressInfo } from "node:net";
18
18
  import { join } from "node:path";
@@ -35,7 +35,7 @@ import {
35
35
  shellAssetResponse,
36
36
  } from "../gateway/index.ts";
37
37
  import { appendEvent } from "../interaction/index.ts";
38
- import type { LedgerOwner } from "../ledger/index.ts";
38
+ import type { Ledger, LedgerOwner } from "../ledger/index.ts";
39
39
  import type { Environment, Log } from "../log.ts";
40
40
  import { type Api, createApi } from "./api.ts";
41
41
  import { type Authorization, createAuthorization } from "./auth.ts";
@@ -47,7 +47,7 @@ import { createHandle } from "./handle.ts";
47
47
  import { type HostedHome, type HostedServices, openHostedHome } from "./hosted.ts";
48
48
  import { type HomeOwner, homeUnavailable } from "./hosted-pages.ts";
49
49
  import { createRemoteMcp, serverDocs } from "./mcp.ts";
50
- import { createMeter, type Meter } from "./metering.ts";
50
+ import { createMeter, heldLevels, type Meter } from "./metering.ts";
51
51
  import { createClients } from "./oauth-clients.ts";
52
52
  import { loadOperator, type Operator } from "./operator.ts";
53
53
  import { type BuiltInProvider, builtInProviders } from "./providers.ts";
@@ -136,27 +136,28 @@ export async function startServer(options: ServerOptions): Promise<RemoteServer>
136
136
  * health check is never counted. Without the setting there is no limit.
137
137
  */
138
138
  const perIpRequests = rateOf(config.rateLimits?.perIp?.requests);
139
- /** Who owns a home, as its pages' sender line names them (D161). */
139
+ /**
140
+ * Who owns a home, as its pages' sender line names them (D161): the account's name, and the
141
+ * verifier its first identity recorded when its provider named the person (MT-03), never the
142
+ * configuration now, so a provider renamed or retired since changes no sender line. A name the
143
+ * development provider took on trust, or one no provider verified, carries none.
144
+ */
140
145
  const ownerOf = (homeId: string): HomeOwner => {
141
146
  const row = data.directory.read((db) =>
142
- db.get<{ account: string; name: string | null; provider: string | null }>(
143
- `SELECT a.id AS account, a.name, (SELECT i.provider FROM identity i WHERE i.account_id = a.id
144
- ORDER BY i.linked_at LIMIT 1) AS provider
145
- FROM home h JOIN account a ON a.id = h.owner_account_id WHERE h.id = ?`,
147
+ db.get<{ account: string; name: string | null; verified_by: string | null }>(
148
+ `SELECT a.id AS account, a.name, i.verified_by
149
+ FROM home h JOIN account a ON a.id = h.owner_account_id
150
+ LEFT JOIN identity i ON i.rowid = (SELECT rowid FROM identity WHERE account_id = a.id
151
+ ORDER BY linked_at, rowid LIMIT 1)
152
+ WHERE h.id = ?`,
146
153
  homeId,
147
154
  ),
148
155
  );
149
156
  if (!row) return { account: "" };
150
- const provider = config.identityProviders?.find((candidate) => candidate.id === row.provider);
151
- // A name the development provider took on trust is unverified (D161).
152
- const verifiedBy =
153
- provider && provider.kind !== "development"
154
- ? (provider.label ?? (provider.kind === "github" ? "GitHub" : provider.id))
155
- : undefined;
156
157
  return {
157
158
  account: row.account,
158
159
  ...(row.name !== null ? { name: row.name } : {}),
159
- ...(verifiedBy !== undefined ? { verifiedBy } : {}),
160
+ ...(row.verified_by !== null ? { verifiedBy: row.verified_by } : {}),
160
161
  };
161
162
  };
162
163
  const services = (): HostedServices => ({
@@ -194,6 +195,9 @@ export async function startServer(options: ServerOptions): Promise<RemoteServer>
194
195
  domains: { active: config.domains.active, spares: config.domains.spares ?? [] },
195
196
  shellDir,
196
197
  services: services(),
198
+ ...(Number(options.env["MOSTRA_TEST_SESSION_TOUCH_MS"]) > 0
199
+ ? { sessionTouchMs: Number(options.env["MOSTRA_TEST_SESSION_TOUCH_MS"]) }
200
+ : {}),
197
201
  relay: {
198
202
  waitingRunsPerArtifact: config.relay?.waitingRunsPerArtifact,
199
203
  drainPerSecond: config.relay?.drainPerSecond,
@@ -245,6 +249,16 @@ export async function startServer(options: ServerOptions): Promise<RemoteServer>
245
249
  handle,
246
250
  directory: data.directory,
247
251
  log,
252
+ // An invitation's link is built when it is handed over, never kept in the queue (D168).
253
+ invitationLink: async (homeId, tokenId) => {
254
+ // A home the directory no longer has can't build a link: its invitations go, while one
255
+ // that is only closed, drained or failing to open is tried again later.
256
+ const known = data.directory.read((db) =>
257
+ db.get("SELECT 1 FROM home WHERE id = ?", homeId),
258
+ );
259
+ if (known === undefined) return undefined;
260
+ return (await data.home(homeId)).assembled.invitationLink(tokenId);
261
+ },
248
262
  ...(Number(options.env["MOSTRA_TEST_OPERATOR_DISPATCH_MS"]) > 0
249
263
  ? { dispatchMs: Number(options.env["MOSTRA_TEST_OPERATOR_DISPATCH_MS"]) }
250
264
  : {}),
@@ -253,6 +267,8 @@ export async function startServer(options: ServerOptions): Promise<RemoteServer>
253
267
  await data.close();
254
268
  throw error;
255
269
  }
270
+ // A held file recorded before sizes were kept (directory migration 6) takes its stored size once.
271
+ fillHeldSizes(data.directory, join(options.data, "files"), log);
256
272
  routing = createRouting({
257
273
  apiHost: new URL(config.apiOrigin).host,
258
274
  domains: () => [config.domains.active, ...(config.domains.spares ?? [])],
@@ -269,6 +285,11 @@ export async function startServer(options: ServerOptions): Promise<RemoteServer>
269
285
  ? { windowMs: Number(options.env["MOSTRA_TEST_METER_WINDOW_MS"]) }
270
286
  : {}),
271
287
  activeHomes: () => data.open().map((home) => ({ home, account: ownerOf(home).account })),
288
+ // `bytes.held` (MT-03): each home's running total, sent when it changed, and all in a snapshot.
289
+ held: heldLevels(data.directory),
290
+ ...(Number(options.env["MOSTRA_TEST_HELD_SNAPSHOT_MS"]) > 0
291
+ ? { snapshotMs: Number(options.env["MOSTRA_TEST_HELD_SNAPSHOT_MS"]) }
292
+ : {}),
272
293
  });
273
294
  auth = createAuthorization({
274
295
  directory: data.directory,
@@ -648,3 +669,39 @@ export async function startServer(options: ServerOptions): Promise<RemoteServer>
648
669
  },
649
670
  };
650
671
  }
672
+
673
+ /**
674
+ * Gives each `home_file` row recorded before sizes were kept (directory migration 6) the size of
675
+ * its stored file, so `bytes.held` counts it (MT-03); the triggers add it to the home's total. A
676
+ * file that is gone holds nothing on disk, so its row takes 0 and is never read again.
677
+ */
678
+ function fillHeldSizes(directory: Ledger, filesDir: string, log: Log): void {
679
+ const rows = directory.read((db) =>
680
+ db.all<{ home_id: string; sha256: string }>(
681
+ "SELECT home_id, sha256 FROM home_file WHERE size IS NULL",
682
+ ),
683
+ );
684
+ if (rows.length === 0) return;
685
+ const sizes = new Map<string, number>();
686
+ let missing = 0;
687
+ for (const row of rows) {
688
+ if (sizes.has(row.sha256)) continue;
689
+ try {
690
+ sizes.set(row.sha256, statSync(join(filesDir, row.sha256)).size);
691
+ } catch {
692
+ sizes.set(row.sha256, 0);
693
+ missing += 1;
694
+ }
695
+ }
696
+ directory.write((db) => {
697
+ for (const row of rows) {
698
+ db.run(
699
+ "UPDATE home_file SET size = ? WHERE home_id = ? AND sha256 = ? AND size IS NULL",
700
+ sizes.get(row.sha256) ?? 0,
701
+ row.home_id,
702
+ row.sha256,
703
+ );
704
+ }
705
+ });
706
+ log.info("server.held_sizes_filled", { files: sizes.size, missing });
707
+ }
@@ -2,7 +2,10 @@
2
2
  * Metering for an operator (INTERFACES §18.6, D165 item 9): counters kept in memory for a window,
3
3
  * then handed to the operator's `metering.record` as one batch with a stable `batchId`, through
4
4
  * the durable outbound queue, so a batch is delivered at least once across restarts. With no
5
- * metering port nothing is counted.
5
+ * metering port nothing is counted. Besides the sums, windows carry one level, `bytes.held`: what
6
+ * a home holds now, sent when it changes (and 0 once when it holds nothing any more), and for every
7
+ * home that holds anything at the first window after a start and once a day after (MT-03). A
8
+ * window's counters go out in batches of at most {@link MAX_COUNTERS}.
6
9
  *
7
10
  * Views carry `viewerKey`, a monthly pseudonymous key: an HMAC of the viewer's subject under a key
8
11
  * the server makes for each month (`<data>/keys/metering-<YYYY-MM>`), so an operator can count
@@ -14,11 +17,23 @@ import { createHmac, randomBytes, randomUUID } from "node:crypto";
14
17
  import { readFileSync, writeFileSync } from "node:fs";
15
18
  import { join } from "node:path";
16
19
  import type { MeterCounter, MeterName } from "@mostra/protocol/operator";
20
+ import type { Ledger } from "../ledger/index.ts";
17
21
  import type { Log } from "../log.ts";
18
22
  import type { Operator } from "./operator.ts";
19
23
 
20
24
  /** How long one batch's window lasts. */
21
25
  const WINDOW_MS = 60_000;
26
+ /** How often every home that holds anything reports its level again, changed or not. */
27
+ const SNAPSHOT_MS = 24 * 60 * 60 * 1000;
28
+ /** The most counters one batch carries; a window with more sends several batches. */
29
+ export const MAX_COUNTERS = 1000;
30
+
31
+ /** One home's held level (`bytes.held`, MT-03). */
32
+ export interface HeldLevel {
33
+ readonly home: string;
34
+ readonly account: string;
35
+ readonly bytes: number;
36
+ }
22
37
 
23
38
  /** What one counter is counted under, besides its name. */
24
39
  export interface MeterScope {
@@ -53,6 +68,21 @@ export interface MeterOptions {
53
68
  readonly windowMs?: number;
54
69
  /** Seconds each open home was active, added at every window. */
55
70
  readonly activeHomes?: () => readonly { readonly home: string; readonly account: string }[];
71
+ /**
72
+ * The homes' held levels for `bytes.held` (MT-03), kept durably by the caller so a change made
73
+ * just before a stop, or while nothing was reported, is still sent after a restart.
74
+ */
75
+ readonly held?: {
76
+ /**
77
+ * The levels to report: each home whose level changed since it was last reported, or with
78
+ * `full`, also every home that holds anything (or last reported more than nothing).
79
+ */
80
+ pending(full: boolean): readonly HeldLevel[];
81
+ /** The levels were queued: each is reported unless its home's level changed meanwhile. */
82
+ reported(levels: readonly HeldLevel[]): void;
83
+ };
84
+ /** How often every held level is sent again; a day unless a test shortens it. */
85
+ readonly snapshotMs?: number;
56
86
  }
57
87
 
58
88
  /** Creates the meter. */
@@ -63,6 +93,9 @@ export function createMeter(options: MeterOptions): Meter {
63
93
  const counters = new Map<string, { counter: MeterCounter; value: number }>();
64
94
  let from = now();
65
95
  const monthKeys = new Map<string, Buffer>();
96
+ const snapshotMs = options.snapshotMs ?? SNAPSHOT_MS;
97
+ /** When every level was last sent; never, so the first window after a start sends them all. */
98
+ let snapshotAt = Number.NEGATIVE_INFINITY;
66
99
 
67
100
  const monthKey = (): Buffer => {
68
101
  const month = new Date(now()).toISOString().slice(0, 7);
@@ -94,19 +127,39 @@ export function createMeter(options: MeterOptions): Meter {
94
127
  add("home.activeSeconds", { account: active.account, home: active.home }, seconds);
95
128
  }
96
129
  }
97
- if (counters.size === 0) {
98
- from = to;
99
- return;
100
- }
101
- const batch = {
102
- batchId: randomUUID(),
103
- from: new Date(from).toISOString(),
104
- to: new Date(to).toISOString(),
105
- counters: [...counters.values()].map(({ counter, value }) => ({ ...counter, value })),
106
- };
130
+ // `bytes.held` is a level, not a sum: a home whose level changed reports it, and every home
131
+ // that holds anything reports it again at the first window after a start and once a day.
132
+ const full = to - snapshotAt >= snapshotMs;
133
+ const levels = options.held?.pending(full) ?? [];
134
+ if (full) snapshotAt = to;
135
+ const held: MeterCounter[] = levels
136
+ .filter((level) => level.account !== "" && level.bytes >= 0)
137
+ .map((level) => ({
138
+ name: "bytes.held",
139
+ account: level.account,
140
+ home: level.home,
141
+ value: level.bytes,
142
+ }));
143
+ const all = [
144
+ ...[...counters.values()].map(({ counter, value }) => ({ ...counter, value })),
145
+ ...held,
146
+ ];
107
147
  counters.clear();
148
+ if (all.length > 0) {
149
+ const window = { from: new Date(from).toISOString(), to: new Date(to).toISOString() };
150
+ for (let start = 0; start < all.length; start += MAX_COUNTERS) {
151
+ options.operator.enqueue({
152
+ port: "metering",
153
+ batch: {
154
+ batchId: randomUUID(),
155
+ ...window,
156
+ counters: all.slice(start, start + MAX_COUNTERS),
157
+ },
158
+ });
159
+ }
160
+ }
161
+ if (levels.length > 0) options.held?.reported(levels);
108
162
  from = to;
109
- options.operator.enqueue({ port: "metering", batch });
110
163
  };
111
164
 
112
165
  const add = (name: MeterName, scope: MeterScope, value = 1): void => {
@@ -154,3 +207,55 @@ export function createMeter(options: MeterOptions): Meter {
154
207
  },
155
208
  };
156
209
  }
210
+
211
+ /**
212
+ * The held levels of a server's homes, from its directory (MT-03): each home's running total in
213
+ * `home.held_bytes`, which `home_file`'s triggers keep in the transaction of every change, and
214
+ * `held_dirty`, set by them until the level is queued, so a change made just before a stop is
215
+ * still reported after the restart. A level is marked reported only while it is still the home's.
216
+ */
217
+ export function heldLevels(directory: Ledger): NonNullable<MeterOptions["held"]> {
218
+ return {
219
+ pending: (full) =>
220
+ directory.write((db) => {
221
+ const rows = db.all<{
222
+ home: string;
223
+ account: string;
224
+ bytes: number;
225
+ reported: number | null;
226
+ }>(
227
+ `SELECT id AS home, owner_account_id AS account, held_bytes AS bytes,
228
+ held_reported AS reported
229
+ FROM home
230
+ WHERE held_dirty = 1${full ? " OR held_bytes > 0 OR COALESCE(held_reported, 0) > 0" : ""}`,
231
+ );
232
+ const levels: HeldLevel[] = [];
233
+ for (const row of rows) {
234
+ // Outside a snapshot, a change that came back to the level last sent, or a home that
235
+ // never held anything, has nothing new to say.
236
+ if (!full && row.bytes === (row.reported ?? 0)) {
237
+ db.run(
238
+ "UPDATE home SET held_dirty = 0 WHERE id = ? AND held_bytes = ?",
239
+ row.home,
240
+ row.bytes,
241
+ );
242
+ continue;
243
+ }
244
+ if (row.reported === null && row.bytes === 0) continue;
245
+ levels.push({ home: row.home, account: row.account, bytes: row.bytes });
246
+ }
247
+ return levels;
248
+ }),
249
+ reported: (levels) =>
250
+ directory.write((db) => {
251
+ for (const level of levels) {
252
+ db.run(
253
+ "UPDATE home SET held_reported = ?, held_dirty = 0 WHERE id = ? AND held_bytes = ?",
254
+ level.bytes,
255
+ level.home,
256
+ level.bytes,
257
+ );
258
+ }
259
+ }),
260
+ };
261
+ }