@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/adapters/streams/s2.js

@@ -5,12 +5,12 @@
  *
  * ## Layout
  *
- * - One basin per Tenant, named by `tenantBasinName` (`streams/basin.ts`):
- *   `<basinPrefix>tn-<ulid>` for a Tenant id `tn_<ulid>`.
- * - The basin is created with `createStreamOnAppend`, so `sessions/<id>/<incarnation>`,
- *   `tenant/work` and `tenant/control` come into existence on their first
- *   append. Its default stream config sets infinite retention, which session
- *   streams keep; the work and control streams are created with a one-day
+ * - One basin per Tenant basin generation, named by `tenantBasinName` (`streams/basin.ts`):
+ *   `<basinPrefix>tn-<ulid>` for a Tenant id `tn_<ulid>`, `…-<g base36>` for generation g.
+ * - The basin is created with `createStreamOnAppend` and `createStreamOnRead`, so
+ *   `sessions/<id>` and `tenant/control` come into existence on first use. Its
+ *   default stream config sets infinite retention, which session streams
+ *   keep; the control stream is created with a one-day
  *   age-based retention instead (signals are latency hints, not history).
  * - Bodies are JSON text in string records. Record timestamps are S2 arrival
  *   times.
@@ -27,7 +27,7 @@
  *   explicit `{ infinite: {} }` retention to keep session history; this adapter
  *   sets it as the basin default, and s2-lite honours it (a new stream reports
  *   `infinite`). A `streamConfig` sent with an append that creates the stream
- *   is honoured too (used for the work and control streams). `deleteOnEmpty`
+ *   is honoured too (used for the control stream). `deleteOnEmpty`
  *   defaults to disabled (`minAgeSecs: 0`).
  * - **Stream deletion** is immediate for our purposes: right after `DELETE`,
  *   `checkTail` and reads return 404 `stream_not_found` (new read sessions
@@ -58,9 +58,9 @@
  *   use the SDK's HTTP/2 (s2s) transport, which s2-lite serves over cleartext.
  */
 import { AppendInput, AppendRecord, RangeNotSatisfiableError, S2, S2Error, SeqNumMismatchError, } from "@s2-dev/streamstore";
-import { tenantBasinName, validateBasinPrefix } from "../../streams/basin.js";
-import { CONTROL_STREAM, WORK_STREAM, } from "../../streams/types.js";
-/** Retention of the work and control signal streams. */
+import { parseBasin, tenantBasinName, validateBasinPrefix } from "../../streams/basin.js";
+import { CONTROL_STREAM, } from "../../streams/types.js";
+/** Retention of the control signal stream. */
 const SIGNAL_RETENTION_SECS = 24 * 60 * 60;
 /** Records per unary read while reading history. */
 const HISTORY_PAGE = 1000;
@@ -99,7 +99,7 @@ class S2Streams {
             return AppendRecord.string({ body });
         }), {
             ...(options.matchSeq !== undefined ? { matchSeqNum: options.matchSeq } : {}),
-            ...(stream === WORK_STREAM || stream === CONTROL_STREAM
+            ...(stream === CONTROL_STREAM
                 ? { streamConfig: { retentionPolicy: { ageSecs: SIGNAL_RETENTION_SECS } } }
                 : {}),
         });
@@ -155,6 +155,9 @@ class S2Streams {
                     basin,
                     config: {
                         createStreamOnAppend: true,
+                        // A reader that arrives before a session's first event creates the
+                        // stream and follows it live, instead of polling until it exists.
+                        createStreamOnRead: true,
                         defaultStreamConfig: { retentionPolicy: { infinite: {} } },
                     },
                 }, { signal: this.closing.signal });
@@ -171,15 +174,24 @@ class S2Streams {
             }
         }
     }
-    async deleteTenant(tenantId) {
+    async deleteTenant(tenantId, options = {}) {
         this.checkOpen();
-        try {
-            await this.s2.basins.delete({ basin: this.basinName(tenantId) }, { signal: this.closing.signal });
-        }
-        catch (error) {
-            if (!isMissing(error))
-                throw error;
+        const basins = [this.basinName(tenantId)];
+        // Every later generation's basin too: `<basin>-<g base36>`.
+        if (options.allGenerations && parseBasin(tenantId).generation === 0) {
+            const later = new RegExp(`^${escapeRegExp(basins[0])}-[0-9a-z]{1,2}$`);
+            for await (const info of this.s2.basins.listAll({ prefix: `${basins[0]}-` }, { signal: this.closing.signal }))
+                if (later.test(info.name) && info.deletedAt == null)
+                    basins.push(info.name);
         }
+        for (const basin of basins)
+            try {
+                await this.s2.basins.delete({ basin }, { signal: this.closing.signal });
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
     }
     async deleteStream(tenantId, stream) {
         this.checkOpen();
@@ -256,7 +268,9 @@ class S2Streams {
     /**
      * Follows `stream` from `fromSeq` with S2 read sessions, reopening a session
      * from the next sequence whenever one ends or fails, until aborted, closed,
-     * or the Tenant's basin is gone. A missing stream is polled until it exists.
+     * or the Tenant's basin is gone. Basins create a stream on read, so a reader
+     * that arrives before the first append waits on the live session instead of
+     * polling.
      */
     async *readLive(tenantId, stream, fromSeq, signal) {
         const aborted = anySignal(signal, this.closing.signal);
@@ -288,7 +302,7 @@ class S2Streams {
                     if ((isMissing(error) || isCode(error, "stream_deletion_pending")) &&
                         (await this.basinGone(tenantId, aborted)))
                         return;
-                    // Stream not created yet, or S2 unreachable: retry below.
+                    // S2 unreachable, or a stream being deleted: retry below.
                 }
                 await sleep(delay, aborted);
                 delay = Math.min(delay * 2, RETRY_MAX_MS);
@@ -343,6 +357,9 @@ function isTransactionConflict(error) {
 function isTenantGone(error) {
     return isCode(error, "basin_not_found") || isCode(error, "basin_deletion_pending");
 }
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function anySignal(...signals) {
     return AbortSignal.any(signals.filter((s) => s !== undefined));
 }

package/dist/admin-openapi.json

@@ -0,0 +1,570 @@
+{
+  "openapi": "3.2.0",
+  "info": {
+    "title": "Nylorun Runtime: Admin API",
+    "version": "0.15.0-beta",
+    "description": "The Host's status, its Tenant's state and shutdown, with the admin key. Served on the operator listener when the Host has one; the public listener answers these routes with the opaque 404.",
+    "x-nylorun-protocol": {
+      "min": 4,
+      "max": 5,
+      "features": [
+        "runtime-tenants",
+        "admin-status",
+        "studio-principal",
+        "action-endpoints",
+        "tenant-fixture-model",
+        "transcript-events",
+        "derived-principals",
+        "subject-headers",
+        "subject-tokens",
+        "browser-access",
+        "ag-ui-endpoint",
+        "a2a-endpoint",
+        "action-endpoints"
+      ]
+    }
+  },
+  "servers": [
+    {
+      "url": "{origin}",
+      "description": "The operator listener: the local stack's, or where yours runs",
+      "variables": {
+        "origin": {
+          "default": "http://localhost:8788"
+        }
+      }
+    }
+  ],
+  "components": {
+    "securitySchemes": {
+      "adminKey": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "The Host's admin key (`host-credentials.json`). Never a Tenant bearer."
+      }
+    },
+    "schemas": {
+      "AdminStatus": {
+        "type": "object",
+        "properties": {
+          "service": {
+            "type": "string",
+            "minLength": 1
+          },
+          "version": {
+            "type": "string",
+            "minLength": 1
+          },
+          "protocol": {
+            "type": "object",
+            "properties": {
+              "min": {
+                "type": "integer"
+              },
+              "max": {
+                "type": "integer"
+              },
+              "features": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "required": [
+              "min",
+              "max",
+              "features"
+            ],
+            "additionalProperties": false
+          },
+          "tenant": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "minLength": 1
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "state": {
+                "type": "string",
+                "enum": [
+                  "open",
+                  "unavailable"
+                ]
+              },
+              "envelope": {
+                "type": [
+                  "object",
+                  "null"
+                ],
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "createdAt": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "updatedAt": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "schemaVersion": {
+                    "type": "integer"
+                  }
+                },
+                "required": [
+                  "id",
+                  "name",
+                  "createdAt",
+                  "updatedAt",
+                  "schemaVersion"
+                ],
+                "additionalProperties": false
+              },
+              "cause": {
+                "type": "object",
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "kek-missing",
+                      "corrupt",
+                      "schema-too-new",
+                      "migration-failed",
+                      "envelope-invalid",
+                      "open-timeout",
+                      "open-failed",
+                      "database-layout-old"
+                    ]
+                  },
+                  "message": {
+                    "type": "string"
+                  },
+                  "repair": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "code",
+                  "message",
+                  "repair"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "id",
+              "name",
+              "state",
+              "envelope"
+            ],
+            "additionalProperties": false
+          },
+          "aggregate": {
+            "type": "object",
+            "properties": {
+              "runningSessions": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "inFlightDeliveries": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "pendingActions": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "uncertainEffects": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "relay": {
+                "type": "object",
+                "properties": {
+                  "active": {
+                    "type": "boolean"
+                  },
+                  "pendingTxs": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "pendingRows": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "confirmed": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "reconciliations": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "lastError": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "lagBytes": {
+                    "type": "number",
+                    "minimum": 0
+                  }
+                },
+                "required": [
+                  "active",
+                  "pendingTxs",
+                  "pendingRows",
+                  "confirmed",
+                  "reconciliations",
+                  "lastError"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "runningSessions",
+              "inFlightDeliveries",
+              "pendingActions",
+              "uncertainEffects"
+            ],
+            "additionalProperties": false
+          },
+          "host": {
+            "type": "object",
+            "properties": {
+              "hostId": {
+                "type": "string",
+                "minLength": 1
+              },
+              "url": {
+                "type": "string",
+                "minLength": 1
+              },
+              "pid": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "hostId",
+              "url",
+              "pid"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "required": [
+          "service",
+          "version",
+          "protocol",
+          "tenant",
+          "aggregate"
+        ],
+        "additionalProperties": false
+      },
+      "Rejected": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "rejected"
+            ]
+          },
+          "code": {
+            "type": "string",
+            "enum": [
+              "not_found",
+              "protocol_unsupported",
+              "host_rejected",
+              "origin_rejected",
+              "unsupported_media_type",
+              "connection_missing",
+              "incompatible_host",
+              "subject_invalid",
+              "scope_required",
+              "token_expired",
+              "limit_exceeded",
+              "request_rejected",
+              "invalid_request",
+              "subject_required",
+              "internal_error"
+            ]
+          },
+          "message": {
+            "type": "string"
+          },
+          "details": {},
+          "activeTurnId": {
+            "type": "string"
+          },
+          "requestId": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "status",
+          "code",
+          "message"
+        ]
+      },
+      "ProtocolRejected": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "rejected"
+            ]
+          },
+          "code": {
+            "type": "string",
+            "enum": [
+              "protocol_unsupported"
+            ]
+          },
+          "protocol": {
+            "type": "object",
+            "properties": {
+              "min": {
+                "type": "integer"
+              },
+              "max": {
+                "type": "integer"
+              },
+              "features": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "required": [
+              "min",
+              "max",
+              "features"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "required": [
+          "status",
+          "code",
+          "protocol"
+        ],
+        "additionalProperties": false
+      },
+      "HostShutdownResponse": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "shutting_down"
+            ]
+          }
+        },
+        "required": [
+          "status"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "parameters": {}
+  },
+  "paths": {
+    "/v1/admin/status": {
+      "get": {
+        "summary": "Get the Host's status",
+        "tags": [
+          "Admin"
+        ],
+        "security": [
+          {
+            "adminKey": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Version, protocol, the Tenant and the Host",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AdminStatus"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found: an unknown admin key, or the public listener",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "426": {
+            "description": "`Nylorun-Protocol` missing or unsupported",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProtocolRejected"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/admin/host": {
+      "get": {
+        "summary": "Get the Host's status (alias)",
+        "tags": [
+          "Admin"
+        ],
+        "security": [
+          {
+            "adminKey": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Version, protocol, the Tenant and the Host",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AdminStatus"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found: an unknown admin key, or the public listener",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "426": {
+            "description": "`Nylorun-Protocol` missing or unsupported",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProtocolRejected"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/admin/host/shutdown": {
+      "post": {
+        "summary": "Shut the Host down",
+        "description": "Answers, then stops the Host. Served by a self-hosted Runtime only.",
+        "tags": [
+          "Admin"
+        ],
+        "security": [
+          {
+            "adminKey": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The Host is stopping",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HostShutdownResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found: an unknown admin key, or the public listener",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "426": {
+            "description": "`Nylorun-Protocol` missing or unsupported",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProtocolRejected"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/admin/openapi.json": {
+      "get": {
+        "summary": "Get this document",
+        "tags": [
+          "Admin"
+        ],
+        "security": [
+          {
+            "adminKey": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The Admin API's OpenAPI document"
+          },
+          "404": {
+            "description": "Not found: an unknown admin key, or the public listener",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "426": {
+            "description": "`Nylorun-Protocol` missing or unsupported",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProtocolRejected"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "webhooks": {}
+}