@sixb/server 0.2.2 → 0.2.4

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 (147) hide show
  1. package/README.md +3 -3
  2. package/dist/artifacts/frame.d.ts.map +1 -1
  3. package/dist/auth/scope.d.ts +3 -0
  4. package/dist/auth/scope.d.ts.map +1 -1
  5. package/dist/auth/shared-access.d.ts +23 -0
  6. package/dist/auth/shared-access.d.ts.map +1 -1
  7. package/dist/connectors/http.d.ts +6 -1
  8. package/dist/connectors/http.d.ts.map +1 -1
  9. package/dist/index.js +2777 -683
  10. package/dist/index.js.map +41 -34
  11. package/dist/live/awareness.d.ts +48 -0
  12. package/dist/live/awareness.d.ts.map +1 -0
  13. package/dist/live/room.d.ts +198 -0
  14. package/dist/live/room.d.ts.map +1 -0
  15. package/dist/live/rooms.d.ts +67 -0
  16. package/dist/live/rooms.d.ts.map +1 -0
  17. package/dist/registerRoutes.d.ts.map +1 -1
  18. package/dist/routes/actions.d.ts +3 -3
  19. package/dist/routes/agent-approvals.d.ts +10 -10
  20. package/dist/routes/agent-children.d.ts +2 -2
  21. package/dist/routes/agent-computers.d.ts +32 -0
  22. package/dist/routes/agent-computers.d.ts.map +1 -1
  23. package/dist/routes/agent-runners.d.ts.map +1 -1
  24. package/dist/routes/agents.d.ts +48 -48
  25. package/dist/routes/artifact-frames.d.ts +2 -1
  26. package/dist/routes/artifact-frames.d.ts.map +1 -1
  27. package/dist/routes/artifacts.d.ts +1713 -178
  28. package/dist/routes/artifacts.d.ts.map +1 -1
  29. package/dist/routes/auth.d.ts +21 -21
  30. package/dist/routes/connector-connection-runs.d.ts +124 -5
  31. package/dist/routes/connector-connection-runs.d.ts.map +1 -1
  32. package/dist/routes/connector-connections.d.ts +9 -1
  33. package/dist/routes/connector-connections.d.ts.map +1 -1
  34. package/dist/routes/datasets.d.ts +5 -5
  35. package/dist/routes/events.d.ts +4 -4
  36. package/dist/routes/lake.d.ts +91 -0
  37. package/dist/routes/lake.d.ts.map +1 -0
  38. package/dist/routes/links.d.ts +6 -6
  39. package/dist/routes/logs.d.ts +2 -2
  40. package/dist/routes/model-generations.d.ts +2 -2
  41. package/dist/routes/objects.d.ts +6 -6
  42. package/dist/routes/objects.d.ts.map +1 -1
  43. package/dist/routes/observed-agent-threads.d.ts +7 -7
  44. package/dist/routes/ontology.d.ts +6 -6
  45. package/dist/routes/pipelines.d.ts +8 -4
  46. package/dist/routes/pipelines.d.ts.map +1 -1
  47. package/dist/routes/projections.d.ts +2 -2
  48. package/dist/routes/share-grants.d.ts +9 -9
  49. package/dist/routes/shared-access.d.ts +57 -2
  50. package/dist/routes/shared-access.d.ts.map +1 -1
  51. package/dist/routes/status.d.ts +11 -15
  52. package/dist/routes/status.d.ts.map +1 -1
  53. package/dist/routes/syncs.d.ts +5 -2
  54. package/dist/routes/syncs.d.ts.map +1 -1
  55. package/dist/routes/telemetry.d.ts +7 -7
  56. package/dist/routes/webhooks.d.ts.map +1 -1
  57. package/dist/routes/workflows.d.ts +3 -3
  58. package/dist/routes/ws/artifacts.d.ts +57 -0
  59. package/dist/routes/ws/artifacts.d.ts.map +1 -0
  60. package/dist/routes/ws/events.d.ts +8 -7
  61. package/dist/routes/ws/events.d.ts.map +1 -1
  62. package/dist/routes/ws/index.d.ts +2 -1
  63. package/dist/routes/ws/index.d.ts.map +1 -1
  64. package/dist/routes/ws/logs.d.ts +10 -10
  65. package/dist/routes/ws/shared-sockets.d.ts +52 -0
  66. package/dist/routes/ws/shared-sockets.d.ts.map +1 -0
  67. package/dist/schemas/actions.d.ts +7 -7
  68. package/dist/schemas/activity.d.ts +8 -8
  69. package/dist/schemas/agent-approvals.d.ts +27 -27
  70. package/dist/schemas/agents.d.ts +195 -154
  71. package/dist/schemas/agents.d.ts.map +1 -1
  72. package/dist/schemas/ai-accounting.d.ts +12 -12
  73. package/dist/schemas/artifacts.d.ts +2106 -127
  74. package/dist/schemas/artifacts.d.ts.map +1 -1
  75. package/dist/schemas/auth.d.ts +63 -63
  76. package/dist/schemas/connectors.d.ts +180 -20
  77. package/dist/schemas/connectors.d.ts.map +1 -1
  78. package/dist/schemas/datasets.d.ts +44 -44
  79. package/dist/schemas/event-payloads.d.ts +2 -2
  80. package/dist/schemas/events.d.ts +26 -26
  81. package/dist/schemas/events.d.ts.map +1 -1
  82. package/dist/schemas/files.d.ts +12 -0
  83. package/dist/schemas/files.d.ts.map +1 -1
  84. package/dist/schemas/lake.d.ts +251 -0
  85. package/dist/schemas/lake.d.ts.map +1 -0
  86. package/dist/schemas/lineage.d.ts +56 -56
  87. package/dist/schemas/logs.d.ts +18 -18
  88. package/dist/schemas/models.d.ts +4 -4
  89. package/dist/schemas/objects.d.ts.map +1 -1
  90. package/dist/schemas/ontology.d.ts +14 -14
  91. package/dist/schemas/pipelines.d.ts +70 -48
  92. package/dist/schemas/pipelines.d.ts.map +1 -1
  93. package/dist/schemas/projections.d.ts +14 -14
  94. package/dist/schemas/projections.d.ts.map +1 -1
  95. package/dist/schemas/share-grants.d.ts +30 -30
  96. package/dist/schemas/shared-access.d.ts +17 -4
  97. package/dist/schemas/shared-access.d.ts.map +1 -1
  98. package/dist/schemas/status.d.ts +59 -79
  99. package/dist/schemas/status.d.ts.map +1 -1
  100. package/dist/schemas/syncs.d.ts +26 -10
  101. package/dist/schemas/syncs.d.ts.map +1 -1
  102. package/dist/schemas/telemetry.d.ts +26 -26
  103. package/dist/schemas/workflows.d.ts +19 -19
  104. package/dist/server.d.ts +13 -0
  105. package/dist/server.d.ts.map +1 -1
  106. package/dist/utils/ws.d.ts +3 -0
  107. package/dist/utils/ws.d.ts.map +1 -1
  108. package/package.json +11 -7
  109. package/src/artifacts/frame.ts +4 -13
  110. package/src/auth/scope.ts +10 -1
  111. package/src/auth/shared-access.ts +108 -12
  112. package/src/connectors/http.ts +35 -1
  113. package/src/live/README.md +136 -0
  114. package/src/live/awareness.ts +141 -0
  115. package/src/live/room.ts +933 -0
  116. package/src/live/rooms.ts +288 -0
  117. package/src/registerRoutes.ts +2 -0
  118. package/src/routes/agent-computers.ts +59 -1
  119. package/src/routes/agent-runners.ts +1 -0
  120. package/src/routes/artifact-frames.ts +40 -12
  121. package/src/routes/artifacts.ts +713 -28
  122. package/src/routes/connector-connection-runs.ts +7 -12
  123. package/src/routes/connector-connections.ts +10 -7
  124. package/src/routes/lake.ts +73 -0
  125. package/src/routes/objects.ts +3 -9
  126. package/src/routes/pipelines.ts +1 -0
  127. package/src/routes/shared-access.ts +53 -1
  128. package/src/routes/status.ts +9 -4
  129. package/src/routes/syncs.ts +1 -0
  130. package/src/routes/webhooks.ts +44 -3
  131. package/src/routes/ws/artifacts.ts +138 -0
  132. package/src/routes/ws/events.ts +7 -2
  133. package/src/routes/ws/index.ts +13 -2
  134. package/src/routes/ws/shared-sockets.ts +152 -0
  135. package/src/schemas/agents.ts +11 -0
  136. package/src/schemas/artifacts.ts +255 -18
  137. package/src/schemas/connectors.ts +17 -2
  138. package/src/schemas/files.ts +12 -0
  139. package/src/schemas/lake.ts +53 -0
  140. package/src/schemas/objects.ts +1 -0
  141. package/src/schemas/pipelines.ts +2 -0
  142. package/src/schemas/projections.ts +2 -2
  143. package/src/schemas/shared-access.ts +16 -0
  144. package/src/schemas/status.ts +16 -22
  145. package/src/schemas/syncs.ts +2 -0
  146. package/src/server.ts +35 -4
  147. package/src/utils/ws.ts +7 -0
@@ -1,5 +1,6 @@
1
1
  import { createHash } from "node:crypto"
2
2
  import type { SixbHostView } from "@sixb/core"
3
+ import { ARTIFACT_LIVE_ROUTE } from "@sixb/core/artifacts/live"
3
4
  import {
4
5
  generateCsrfToken,
5
6
  getCookie,
@@ -7,7 +8,11 @@ import {
7
8
  verifyDoubleSubmitCsrf,
8
9
  } from "@sixb/core/internal/auth"
9
10
  import { matchesPathPattern, normalizeRoutePath, SIXB_API_ROUTES } from "@sixb/core/internal/http"
10
- import { type SharedSessionContext, SharedSessionProtocol } from "@sixb/core/internal/shares"
11
+ import {
12
+ guestName,
13
+ type SharedSessionContext,
14
+ SharedSessionProtocol,
15
+ } from "@sixb/core/internal/shares"
11
16
  import { hasForegroundSessionActivity } from "./session-activity"
12
17
 
13
18
  export const SHARED_ACCESS_GRANT_HEADER_NAME = "x-sixb-share-grant"
@@ -15,14 +20,38 @@ const SHARED_ACCESS_GRANT_QUERY_PARAM = "shareGrant"
15
20
 
16
21
  const SHARED_SESSION_COOKIE_PREFIX = "sixb_share_session_"
17
22
  const SHARED_CSRF_COOKIE_PREFIX = "sixb_share_csrf_"
18
- const SHARED_COOKIE_PATH = "/api"
23
+ /**
24
+ * The session cookie reaches the API and its sockets, whose upgrade a browser sends with cookies
25
+ * but no header of ours. It stays `SameSite=Strict` and `HttpOnly`, and every request, an upgrade
26
+ * included, must come from an allowed origin: another site's page cannot ride it. The CSRF cookie
27
+ * is only ever needed beside a mutation, so it stays under `/api`.
28
+ */
29
+ const SHARED_SESSION_COOKIE_PATH = "/"
30
+ const SHARED_CSRF_COOKIE_PATH = "/api"
31
+ /** Where session cookies were set before they reached sockets: cleared with the current ones. */
32
+ const LEGACY_SHARED_SESSION_COOKIE_PATH = "/api"
19
33
  const STORED_IDENTIFIER_MAX_LENGTH = 128
20
34
 
21
35
  const SHARED_SESSION_ROUTES = SIXB_API_ROUTES.filter((route) => route.sharedSession)
22
- const SHARED_FILE_CONTENT_ROUTES = SHARED_SESSION_ROUTES.filter(
23
- (route) =>
24
- (route.method === "GET" || route.method === "HEAD") && route.path.endsWith("/files/content")
25
- )
36
+
37
+ /**
38
+ * The sockets a shared link's session may open: the live artifacts it reads, which it watches,
39
+ * and the event stream, which passes it only those artifacts' events.
40
+ */
41
+ const SHARED_SESSION_SOCKETS: readonly string[] = [ARTIFACT_LIVE_ROUTE, "/ws/events"]
42
+
43
+ /**
44
+ * Where the grant may be named in the query: what `<img>`, `<video>` and download links load, and
45
+ * the sockets, none of which can send a header.
46
+ */
47
+ const SHARED_QUERY_SELECTOR_ROUTES = [
48
+ ...SHARED_SESSION_ROUTES.filter(
49
+ (route) =>
50
+ (route.method === "GET" || route.method === "HEAD") &&
51
+ (route.path.endsWith("/content") || route.path.endsWith("/preview"))
52
+ ),
53
+ ...SHARED_SESSION_SOCKETS.map((path) => ({ method: "GET", path })),
54
+ ]
26
55
 
27
56
  export interface SixbSharedAccessOptions {
28
57
  /** Sliding inactivity window, always bounded by the grant's absolute expiration. */
@@ -54,6 +83,12 @@ export type SharedAccessSignOutResult =
54
83
  | { readonly kind: "csrf" }
55
84
  | { readonly kind: "signedOut"; readonly setCookies: readonly string[] }
56
85
 
86
+ export type SharedAccessGuestNameResult =
87
+ | { readonly kind: "invalid"; readonly setCookies: readonly string[] }
88
+ | { readonly kind: "csrf" }
89
+ | { readonly kind: "unnamed" }
90
+ | ({ readonly kind: "named" } & ResolvedSharedAccess)
91
+
57
92
  /**
58
93
  * Selects shared authority before ambient browser or bearer authentication.
59
94
  *
@@ -64,6 +99,7 @@ export class SharedAccessBoundary {
64
99
  private readonly host: SixbHostView
65
100
  private readonly options: SixbSharedAccessOptions
66
101
  private protocol: SharedSessionProtocol | undefined
102
+ private readonly guestNamed = new Set<(sessionId: string) => void>()
67
103
 
68
104
  constructor(host: SixbHostView, options: SixbSharedAccessOptions = {}) {
69
105
  this.host = host
@@ -176,6 +212,7 @@ export class SharedAccessBoundary {
176
212
  serializeSharedCookie({
177
213
  request,
178
214
  name: names.csrf,
215
+ path: SHARED_CSRF_COOKIE_PATH,
179
216
  value: csrfToken,
180
217
  expiresAt: context.expiresAt,
181
218
  maxAge: cookieMaxAge(context.expiresAt),
@@ -208,6 +245,47 @@ export class SharedAccessBoundary {
208
245
  return { kind: "signedOut", setCookies: clearCookies }
209
246
  }
210
247
 
248
+ /**
249
+ * Keeps the name the session's visitor gives, which their comments and presence carry. Like
250
+ * sign-out, it needs the session and its CSRF token; `unnamed` for a name that will not do.
251
+ */
252
+ async setGuestName(
253
+ request: Request,
254
+ grantId: string,
255
+ name: string
256
+ ): Promise<SharedAccessGuestNameResult> {
257
+ if (!isStoredIdentifier(grantId)) return { kind: "invalid", setCookies: [] }
258
+
259
+ const resolved = await this.resolveSession(request, grantId)
260
+ if (!resolved) return { kind: "invalid", setCookies: this.clearCookieHeaders(request, grantId) }
261
+
262
+ if (!verifyDoubleSubmitCsrf(request, { cookieName: sharedCookieNames(grantId).csrf })) {
263
+ return { kind: "csrf" }
264
+ }
265
+
266
+ const kept = guestName(name)
267
+ if (kept === null) return { kind: "unnamed" }
268
+
269
+ const context = await this.getProtocol().setGuestName(resolved.context, kept)
270
+ if (!context) return { kind: "invalid", setCookies: this.clearCookieHeaders(request, grantId) }
271
+
272
+ for (const listener of this.guestNamed) listener(context.sessionId)
273
+ return { kind: "named", context, cookies: resolved.cookies }
274
+ }
275
+
276
+ /** Hears each session whose visitor gave a name through this server. */
277
+ onGuestNamed(listener: (sessionId: string) => void): void {
278
+ this.guestNamed.add(listener)
279
+ }
280
+
281
+ /**
282
+ * The session a socket authenticated when it opened, as it is now: null once it is revoked or
283
+ * expired, or its grant is. Reading it renews nothing.
284
+ */
285
+ current(context: Pick<SharedSessionContext, "grantId" | "sessionId">) {
286
+ return this.getProtocol().current(context)
287
+ }
288
+
211
289
  clearCookieHeaders(request: Request, grantId: string): readonly string[] {
212
290
  if (!isStoredIdentifier(grantId)) return []
213
291
  const names = sharedCookieNames(grantId)
@@ -215,6 +293,16 @@ export class SharedAccessBoundary {
215
293
  serializeSharedCookie({
216
294
  request,
217
295
  name: names.session,
296
+ path: SHARED_SESSION_COOKIE_PATH,
297
+ value: "",
298
+ expiresAt: new Date(0),
299
+ maxAge: 0,
300
+ httpOnly: true,
301
+ }),
302
+ serializeSharedCookie({
303
+ request,
304
+ name: names.session,
305
+ path: LEGACY_SHARED_SESSION_COOKIE_PATH,
218
306
  value: "",
219
307
  expiresAt: new Date(0),
220
308
  maxAge: 0,
@@ -223,6 +311,7 @@ export class SharedAccessBoundary {
223
311
  serializeSharedCookie({
224
312
  request,
225
313
  name: names.csrf,
314
+ path: SHARED_CSRF_COOKIE_PATH,
226
315
  value: "",
227
316
  expiresAt: new Date(0),
228
317
  maxAge: 0,
@@ -245,6 +334,7 @@ export class SharedAccessBoundary {
245
334
  serializeSharedCookie({
246
335
  request: input.request,
247
336
  name: names.session,
337
+ path: SHARED_SESSION_COOKIE_PATH,
248
338
  value: input.sessionValue,
249
339
  expiresAt: input.expiresAt,
250
340
  maxAge,
@@ -253,6 +343,7 @@ export class SharedAccessBoundary {
253
343
  serializeSharedCookie({
254
344
  request: input.request,
255
345
  name: names.csrf,
346
+ path: SHARED_CSRF_COOKIE_PATH,
256
347
  value: input.csrfToken,
257
348
  expiresAt: input.expiresAt,
258
349
  maxAge,
@@ -291,22 +382,24 @@ export function isSharedAccessPublicPath(pathname: string, requestMethod: string
291
382
  ? "session"
292
383
  : method === "POST" && normalizedPathname.endsWith("/sign-out")
293
384
  ? "sign-out"
294
- : null
385
+ : method === "PUT" && normalizedPathname.endsWith("/name")
386
+ ? "name"
387
+ : null
295
388
  if (!suffix) return false
296
389
  return matchesPathPattern(normalizedPathname, `/api/shared-access/:grantId/${suffix}`)
297
390
  }
298
391
 
299
392
  /**
300
- * The header selects the grant. File GET/HEAD routes also accept the selector in the query, because
301
- * `<img>`, `<video>`, and download links cannot send headers. Either way it only names which
302
- * grant cookie to read; the HttpOnly cookie remains the credential.
393
+ * The header selects the grant. File GET/HEAD routes and the sockets also accept the selector in
394
+ * the query, because `<img>`, `<video>`, download links and WebSockets cannot send headers. Either
395
+ * way it only names which grant cookie to read; the HttpOnly cookie remains the credential.
303
396
  */
304
397
  function selectSharedAccessGrant(request: Request): SharedAccessGrantSelection {
305
398
  const header = request.headers.get(SHARED_ACCESS_GRANT_HEADER_NAME)
306
399
  const url = new URL(request.url)
307
400
  const method = request.method.toUpperCase()
308
401
  const pathname = normalizeRoutePath(url.pathname)
309
- const queryValues = SHARED_FILE_CONTENT_ROUTES.some(
402
+ const queryValues = SHARED_QUERY_SELECTOR_ROUTES.some(
310
403
  (route) => route.method === method && matchesPathPattern(pathname, route.path)
311
404
  )
312
405
  ? url.searchParams.getAll(SHARED_ACCESS_GRANT_QUERY_PARAM)
@@ -323,6 +416,8 @@ function selectSharedAccessGrant(request: Request): SharedAccessGrantSelection {
323
416
  export function isSharedSessionRoute(request: Request): boolean {
324
417
  const method = request.method.toUpperCase()
325
418
  const pathname = normalizeRoutePath(new URL(request.url).pathname)
419
+ if (method === "GET" && SHARED_SESSION_SOCKETS.includes(pathname)) return true
420
+
326
421
  return SHARED_SESSION_ROUTES.some(
327
422
  (route) => route.method === method && matchesPathPattern(pathname, route.path)
328
423
  )
@@ -376,6 +471,7 @@ function sharedCookieNames(grantId: string): { readonly session: string; readonl
376
471
  function serializeSharedCookie(input: {
377
472
  readonly request: Request
378
473
  readonly name: string
474
+ readonly path: string
379
475
  readonly value: string
380
476
  readonly expiresAt: Date
381
477
  readonly maxAge: number
@@ -383,7 +479,7 @@ function serializeSharedCookie(input: {
383
479
  }): string {
384
480
  const parts = [
385
481
  `${input.name}=${input.value}`,
386
- `Path=${SHARED_COOKIE_PATH}`,
482
+ `Path=${input.path}`,
387
483
  "SameSite=Strict",
388
484
  `Max-Age=${Math.trunc(input.maxAge)}`,
389
485
  `Expires=${input.expiresAt.toUTCString()}`,
@@ -1,4 +1,4 @@
1
- import type { SixbHostView } from "@sixb/core"
1
+ import { AuthorizationError, type ConnectorConnectionOwner, type SixbHostView } from "@sixb/core"
2
2
  import type {
3
3
  ConnectorConnectionRunView,
4
4
  ConnectorConnectionsRuntime,
@@ -9,6 +9,7 @@ import {
9
9
  isOAuthConnectorDefinition,
10
10
  } from "@sixb/core/internal/connector-connections"
11
11
  import { createSixbError } from "@sixb/core/internal/errors"
12
+ import type { Sixb } from "@sixb/core/internal/request-execution"
12
13
  import type { z } from "zod"
13
14
  import {
14
15
  CONNECTOR_HTTP_ERROR_CODES,
@@ -36,6 +37,39 @@ export function connectorRouteRuntime(
36
37
  return getConnectorConnectionsRuntime(owner)
37
38
  }
38
39
 
40
+ /** The owner a route's `owner` choice names: the project, or the signed-in caller. */
41
+ export function connectorConnectionOwner(
42
+ sixb: Pick<Sixb, "execution">,
43
+ connectorId: string,
44
+ choice: "project" | "me"
45
+ ): ConnectorConnectionOwner {
46
+ if (choice === "project") return { type: "project" }
47
+ const requester = sixb.execution.requestedBy
48
+ if (requester?.type !== "user") {
49
+ throw new AuthorizationError(
50
+ `connection:connector:${connectorId}`,
51
+ "[Sixb] Only a signed-in user can connect their own account."
52
+ )
53
+ }
54
+ return { type: "user", id: requester.id }
55
+ }
56
+
57
+ /** Whether a connection matches a list route's `owner` filter. */
58
+ export function matchesConnectorConnectionOwner(
59
+ sixb: Pick<Sixb, "execution">,
60
+ connection: ConnectorConnectionView,
61
+ choice: "project" | "me" | undefined
62
+ ): boolean {
63
+ if (choice === undefined) return true
64
+ if (choice === "project") return connection.owner.type === "project"
65
+ const requester = sixb.execution.requestedBy
66
+ return (
67
+ connection.owner.type === "user" &&
68
+ requester?.type === "user" &&
69
+ connection.owner.id === requester.id
70
+ )
71
+ }
72
+
39
73
  export function serializeConnectorConnection(
40
74
  connection: ConnectorConnectionView
41
75
  ): z.infer<typeof ConnectorConnectionSchema> {
@@ -0,0 +1,136 @@
1
+ # Live artifacts
2
+
3
+ `/ws/artifacts` lets several people edit a canvas at once. Every connected client holds the
4
+ artifact's open version as a Yjs document (`@sixb/core/artifacts/live`). Each server holding the
5
+ artifact keeps one copy, and writes it back into storage as an ordinary artifact write.
6
+
7
+ | File | Role |
8
+ | --- | --- |
9
+ | `routes/ws/artifacts.ts` | The socket: auth as `/ws/agents`, message parsing, one `LiveRooms` per server |
10
+ | `rooms.ts` | Which artifacts this server holds, joins and leaves, who each connection is, the `artifact.updated` feed |
11
+ | `room.ts` | One artifact: its document, its members, write-back, the live stream, presence |
12
+ | `awareness.ts` | What a connection may say of itself in awareness |
13
+
14
+ ## One history
15
+
16
+ Yjs merges only documents that share a history. Two documents built separately from the same
17
+ files each own their `canvas.json`, and syncing them keeps one by client id. So storage keeps the
18
+ document itself: `ArtifactRecord.document`, the whole encoded state in a blob and the revision
19
+ whose content it holds, replaced with every content write (see
20
+ `packages/core/src/artifacts/live/state.ts`).
21
+
22
+ - Every server loads a room from that state, and every client's document comes from a room. Any
23
+ copy, on any server and after any reload, continues the same history.
24
+ - Every write to a canvas is made into that document, whoever makes it
25
+ (`packages/core/src/artifacts/publish/merge.ts`):
26
+ - A live write-back carries the room's state, which is applied to the stored one.
27
+ - A write of files (the Agent, HTTP) is applied as the change from the files it was made from.
28
+ - A restore, or a retried turn's undo, is applied as the change back to the restored files.
29
+ - A document whose revision is not the artifact's was left behind by a write that stored none: a
30
+ server from before documents were kept, during a rolling deploy, or a repair by hand. Whoever
31
+ loads it, a room or a write, brings it up to the content as the change from the files it holds.
32
+ An artifact that keeps none yet is built from its files.
33
+ - Both are made under a client id derived from what they are made from, so every server makes the
34
+ same document, and the next write stores it again.
35
+
36
+ ## Joining
37
+
38
+ - On `join`, the server reads the person's access to the artifact. `owner` and `update` edit,
39
+ `read` watches, and anything else is refused with `left`.
40
+ - The first join opens the room from the stored document. Other kinds are refused as `not_live`.
41
+ - `joined` says who the connection is (`user`: id, name and color, read once per connection). A
42
+ shared link's guest is read at each join instead, from its session: `guest:<sessionId>`, the
43
+ name they gave, and `guest: true`. Once they give a name, their socket reads it from the session
44
+ (`LiveRooms.refreshUser`): their awareness states take it, and the room shares them again. A name is never an email or an id, since every connection,
45
+ a guest's included, sees the same state: someone who gave none has an empty name.
46
+ - A shared link's socket reads its session again every `SHARED_SOCKET_RECHECK_MS`, and on its next
47
+ message past that (`routes/ws/shared-sockets.ts`): its SDK keeps the authority the upgrade
48
+ proved, so revocation is seen only there. One that ended is closed with 4401.
49
+ - A socket message is at most 64 KiB. A larger sync message is sent in parts (`more: true`, see
50
+ `liveSync`), each its own base64, and assembled per connection and artifact up to
51
+ `MAX_LIVE_SYNC_BYTES`.
52
+ - A watcher may send sync step 1 (to receive the document) and awareness, never an update. An
53
+ editor's access is read again at most every `ACCESS_RECHECK_MS` while it writes, and every
54
+ member's on each write to the artifact and every `MEMBERS_RECHECK_MS`. Losing `update`
55
+ demotes it to a watcher (`access`), and losing `read` removes it (`left`).
56
+
57
+ ## Presence
58
+
59
+ The server vouches for every awareness state it shares:
60
+
61
+ - A connection may speak for awareness clients that nobody else speaks for, up to
62
+ `MAX_AWARENESS_CLIENTS`. It may not speak for another connection's client, another server's, or
63
+ the room's own.
64
+ - Each state it sets is stored with `user` replaced by who the server knows the person to be, and
65
+ without `sixbAgent`.
66
+ - `sixbAgent` is only the server's own state: the boards each Agent turn changed, read from the
67
+ live stream.
68
+
69
+ ## Write-back
70
+
71
+ - An editor's change marks the room dirty. It is written `SAVE_IDLE_MS` after the last change, at
72
+ most `SAVE_MAX_MS` after the first, and at once when the last editor leaves.
73
+ - `flush` writes the room's state through `writeLiveArtifact`, with the SDK of the last editor:
74
+ the public `update` takes files only, and this server-only entry makes the same write from the
75
+ document. The write is authored by that person, bumps the revision, and emits
76
+ `artifact.updated`. If someone
77
+ wrote meanwhile, storage merges both. The room then takes the stored state back under the
78
+ `MERGED` origin, which is never written back again. The document holds no title: the write
79
+ passes the title it last read as `baseTitle`, so a title given since stays.
80
+ - A write-back that changes a board asks for its pictures like any write: in the artifact's one
81
+ preview job, which it replaces, due `BOARD_PREVIEW_JOB.settleMs` later. That is longer than
82
+ `SAVE_MAX_MS`, so a board being typed in is pictured once, after its editors pause.
83
+ - A client's change is tried first on a shadow copy of the document. One that leaves it unreadable
84
+ (`documentFiles` throws) is refused with an `error` before anyone gets it, so a poisoned history
85
+ never spreads or wedges the write-back.
86
+ - A failure leaves the room dirty, reports `status: failed` with the error, and retries:
87
+ - `artifact_not_found`: the room closes and every member gets `left`.
88
+ - An access error: the author is demoted, and another editor is tried at once.
89
+ - `invalid_artifact`: waits for the next change while someone is connected.
90
+ - Anything else: retries with backoff from 2 s doubling to 30 s, for as long as the server runs,
91
+ whether or not anyone still holds the room.
92
+ - Changes are lost only when nobody can write them: the server stops first, or storage refuses
93
+ them (an access error, `invalid_artifact`) once nobody is left who could change that. The room
94
+ then reports `artifact.live_write.failed` to the project's `onError`, through
95
+ `LiveRoomHost.errorReporterHost`, and drops them.
96
+
97
+ ## Writes made elsewhere
98
+
99
+ Every `artifact.updated` for a held artifact queues a `reconcile`, whoever made the write. The
100
+ room applies the stored document, brought up to the content if it was left behind, so unsaved
101
+ edits stay. An artifact that keeps none at all takes the change from the files the room last took
102
+ in. The room's work (flush, reconcile) runs on one queue, one task at a
103
+ time.
104
+
105
+ ## Several servers
106
+
107
+ Two broker streams carry what reaches every server at once. Each record is tagged with the server
108
+ that heard it, so it is not taken back.
109
+
110
+ `artifacts.live.<artifactId>` (10 minutes, 5,000 records):
111
+
112
+ - `update`: a Yjs update an editor made. Other servers apply it under the `REMOTE` origin and show
113
+ it to their members. The server that heard it writes it back. Each other server marks it
114
+ unwritten, and writes it back too `HEARD_SAVE_MS` later, or when its last editor leaves. By then
115
+ that write is normally in storage, and a write that changes nothing is skipped; if the server
116
+ that heard it died, the edit is not lost.
117
+ - Applying an update twice changes nothing, so a room that opens replays the stream from its start,
118
+ to get what was changed since the last write-back.
119
+ - `agent` / `agent-ended`: the boards an Agent turn changed, appended by `run-artifacts` after each
120
+ canvas write and at the turn's end. Each server drops one after `AGENT_PRESENCE_MS` if the turn
121
+ never ends.
122
+
123
+ `artifacts.presence.<artifactId>` (1 minute, 1,000 records) carries `awareness`: what people point
124
+ at, as their server vouched for it. A server shares its people's states at most every
125
+ `AWARENESS_SHARE_MS`, each as it is by then, so moving cursors never push an update out of the
126
+ document's stream.
127
+
128
+ An update the stream no longer holds reaches storage with a write-back, so a server that missed it
129
+ gets it then.
130
+
131
+ ## Lifetime
132
+
133
+ Once the last connection leaves and nothing waits to be written, the room closes and frees its
134
+ document. A client that reconnects later gets a room loaded from storage, with the same history, so
135
+ plain sync brings back what it changed while away. A connection holds at most
136
+ `MAX_LIVE_ARTIFACTS_PER_CONNECTION` artifacts. On server stop, every room writes back first.
@@ -0,0 +1,141 @@
1
+ import { createHash } from "node:crypto"
2
+ import {
3
+ AGENT_AWARENESS_FIELD,
4
+ type ArtifactLiveUser,
5
+ USER_AWARENESS_FIELD,
6
+ } from "@sixb/core/artifacts/live"
7
+ import type { Storage } from "@sixb/core/storage"
8
+ import * as decoding from "lib0/decoding"
9
+ import * as encoding from "lib0/encoding"
10
+
11
+ // What a connection says of itself in awareness, as the server lets others see it: only its own
12
+ // clients' states, each naming the person the server knows it to be, and never the Agent's field,
13
+ // which only servers set.
14
+
15
+ /** The most awareness clients one connection may speak for: a browser tab holds one. */
16
+ export const MAX_AWARENESS_CLIENTS = 4
17
+ /** The most a client's awareness state may weigh, as JSON. */
18
+ export const MAX_AWARENESS_STATE_BYTES = 4 * 1024
19
+
20
+ /** Colors a person's cursor may take: one per person, the same wherever they connect. */
21
+ const COLORS = [
22
+ "#e5484d",
23
+ "#f76b15",
24
+ "#ffc53d",
25
+ "#46a758",
26
+ "#12a594",
27
+ "#0090ff",
28
+ "#8e4ec6",
29
+ "#d6409f",
30
+ ] as const
31
+
32
+ /** What the project's own code, and everyone where nobody signs in, is called. */
33
+ export const PROJECT_NAME = "Project"
34
+
35
+ /**
36
+ * The name others see for someone: a member's profile name, else their email, and the project's
37
+ * for its own code. Null for anyone else, or a member the project no longer knows. Without
38
+ * `email`, for a reader outside the project such as a shared link's guest, a member who gave no
39
+ * name stays unnamed.
40
+ */
41
+ export async function principalName(
42
+ storage: Pick<Storage, "auth">,
43
+ projectId: string,
44
+ principal: { readonly type: string; readonly id: string },
45
+ options: { readonly email?: boolean } = {}
46
+ ): Promise<string | null> {
47
+ if (principal.type === "system") return PROJECT_NAME
48
+ if (principal.type !== "user") return null
49
+
50
+ const record = await storage.auth?.users.getById({ projectId, id: principal.id })
51
+ if (options.email === false) return record?.displayName ?? null
52
+ return record?.displayName ?? record?.email ?? null
53
+ }
54
+
55
+ /**
56
+ * Who a connection is: the member it signed in as, by their profile's name, or the service
57
+ * account or project code it runs as.
58
+ *
59
+ * Everyone in the room sees it, a shared link's guest included, and the server shares one state
60
+ * with all: so it is never an email, nor an id. Someone without a profile name has none, which the
61
+ * app names in the reader's language.
62
+ */
63
+ export async function liveUserOf(
64
+ storage: Pick<Storage, "auth">,
65
+ projectId: string,
66
+ principal: { readonly type: string; readonly id: string } | undefined
67
+ ): Promise<ArtifactLiveUser> {
68
+ if (!principal) return { id: "system", name: PROJECT_NAME, color: colorOf("system") }
69
+
70
+ const id = `${principal.type}:${principal.id}`
71
+ const name = (await principalName(storage, projectId, principal, { email: false })) ?? ""
72
+ return { id, name, color: colorOf(id) }
73
+ }
74
+
75
+ /**
76
+ * Who a shared link's guest is: one per session, by the name they gave, or none yet, marked as a
77
+ * guest so nobody takes them for a member of the same name.
78
+ */
79
+ export function guestLiveUser(sessionId: string, name: string | undefined): ArtifactLiveUser {
80
+ const id = `guest:${sessionId}`
81
+ return { id, name: name ?? "", color: colorOf(id), guest: true }
82
+ }
83
+
84
+ /**
85
+ * An awareness update from a connection, as the server takes it: only the clients it may speak
86
+ * for, each state naming `user`, without the Agent's field, and within its size. Null when none is
87
+ * left, or the update does not read.
88
+ */
89
+ export function vouchedAwareness(
90
+ update: Uint8Array,
91
+ input: {
92
+ readonly user: ArtifactLiveUser
93
+ /** Whether the connection may speak for this awareness client. */
94
+ readonly mayUse: (clientID: number) => boolean
95
+ }
96
+ ): Uint8Array | null {
97
+ const entries: { clientID: number; clock: number; state: string }[] = []
98
+ try {
99
+ const decoder = decoding.createDecoder(update)
100
+ const length = decoding.readVarUint(decoder)
101
+ for (let index = 0; index < length; index += 1) {
102
+ const clientID = decoding.readVarUint(decoder)
103
+ const clock = decoding.readVarUint(decoder)
104
+ const state = vouchedState(decoding.readVarString(decoder), input.user)
105
+ if (state !== undefined && input.mayUse(clientID)) entries.push({ clientID, clock, state })
106
+ }
107
+ } catch {
108
+ return null
109
+ }
110
+ if (entries.length === 0) return null
111
+
112
+ const encoder = encoding.createEncoder()
113
+ encoding.writeVarUint(encoder, entries.length)
114
+ for (const entry of entries) {
115
+ encoding.writeVarUint(encoder, entry.clientID)
116
+ encoding.writeVarUint(encoder, entry.clock)
117
+ encoding.writeVarString(encoder, entry.state)
118
+ }
119
+ return encoding.toUint8Array(encoder)
120
+ }
121
+
122
+ /** A client's state as JSON, naming `user`; `null` stays, for a client that goes. */
123
+ function vouchedState(json: string, user: ArtifactLiveUser): string | undefined {
124
+ if (json.length > MAX_AWARENESS_STATE_BYTES) return undefined
125
+
126
+ const state: unknown = JSON.parse(json)
127
+ if (state === null) return "null"
128
+ if (typeof state !== "object" || Array.isArray(state)) return undefined
129
+
130
+ const {
131
+ [AGENT_AWARENESS_FIELD]: _agent,
132
+ [USER_AWARENESS_FIELD]: _user,
133
+ ...own
134
+ } = state as Record<string, unknown>
135
+ return JSON.stringify({ ...own, [USER_AWARENESS_FIELD]: user })
136
+ }
137
+
138
+ function colorOf(id: string): string {
139
+ const index = createHash("sha256").update(id).digest()[0] ?? 0
140
+ return COLORS[index % COLORS.length] as string
141
+ }