terse-cli 0.9.19 → 0.9.21

package/templates/typescript/terse-transport.js

@@ -0,0 +1,117 @@
+// Generated by terse actor generate; regenerate instead of editing.
+// Terse connection defaults for this generated actor client.
+import { ActorSessionRejectedError, SocketProxy as RuntimeSocketProxy, createActorSessionTransport, createActorTransport, createActorStub as createRuntimeActorStub } from "./runtime/index.js"
+
+export * from "./runtime/index.js"
+
+const DEFAULT_ACTOR_URL = "http://127.0.0.1:7100/v1/projects/local/actors"
+
+let connection
+
+const terseTransport = {
+    invoke(actorName, actorId, method, args) {
+        return currentTransport().invoke(actorName, actorId, method, args)
+    }
+}
+
+/** Use TERSE_ACTOR_URL and TERSE_API_KEY, with local development defaults. */
+export function createActorStub(actorName, actorId, methods, transport = terseTransport) {
+    return createRuntimeActorStub(actorName, actorId, methods, transport)
+}
+
+/** Issue browser WebSocket grants through the selected Terse project. */
+export class SocketProxy {
+    #actors
+    #options
+    #dependencies
+
+    constructor(actors, options = {}, dependencies = {}) {
+        this.#actors = actors
+        this.#options = options
+        this.#dependencies = dependencies
+    }
+
+    async handle(authorization) {
+        const { endpoint, apiKey } = connectionSettings()
+        const setupTimeoutMs = this.#options.setupTimeoutMs ?? configuredSetupTimeoutMs()
+        if (endpoint.kind === "runtime") {
+            const options = { projectId: endpoint.projectId, controlPlaneUrl: endpoint.origin, apiKey: apiKey || undefined, setupTimeoutMs }
+            return new RuntimeSocketProxy(this.#actors, options, this.#dependencies).handle(authorization)
+        }
+        const { actorName, actorId, metadata } = authorization
+        if (!Object.hasOwn(this.#actors, actorName)) throw new Error(`Unknown actor name: ${actorName}`)
+        const response = await (this.#dependencies.fetch ?? globalThis.fetch)(endpoint.actorUrl, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", Accept: "application/json" },
+            body: JSON.stringify({ actorName, actorId, metadata }),
+            signal: AbortSignal.timeout(setupTimeoutMs ?? 10_000),
+            redirect: "error"
+        })
+        if (!response.ok) {
+            await response.body?.cancel()
+            throw new Error(`Actor connection grant could not be issued (HTTP ${response.status})`)
+        }
+        return response.json()
+    }
+}
+
+function currentTransport() {
+    const { endpoint, apiKey } = connectionSettings()
+    const key = JSON.stringify([endpoint.actorUrl, apiKey])
+    if (connection?.key === key) return connection.transport
+    connection?.transport.dispose?.()
+    const transport =
+        endpoint.kind === "runtime"
+            ? createActorTransport({ projectId: endpoint.projectId, controlPlaneUrl: endpoint.origin, apiKey: apiKey || undefined })
+            : createActorSessionTransport({ projectId: endpoint.projectId, getSession: () => requestSession(endpoint, apiKey) })
+    connection = { key, transport }
+    return transport
+}
+
+async function requestSession(endpoint, apiKey) {
+    const response = await globalThis.fetch(`${endpoint.actorUrl}/access`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+        redirect: "error",
+        signal: AbortSignal.timeout(10_000)
+    })
+    if (!response.ok) {
+        await response.body?.cancel()
+        const message = `Actor authorization failed (HTTP ${response.status})`
+        if (response.status === 401 || response.status === 403) throw new ActorSessionRejectedError(message)
+        throw new Error(message)
+    }
+    return response.json()
+}
+
+function connectionSettings() {
+    const environment = globalThis.process?.env ?? {}
+    const endpoint = parseActorEndpoint(environment.TERSE_ACTOR_URL?.trim() || DEFAULT_ACTOR_URL)
+    const apiKey = environment.TERSE_API_KEY?.trim() || ""
+    const local = endpoint.kind === "runtime" && ["localhost", "127.0.0.1", "[::1]"].includes(new URL(endpoint.origin).hostname)
+    if (!apiKey && !local) throw new Error("Missing TERSE_API_KEY. Set it in the .env of the project calling the actor.")
+    return { endpoint, apiKey }
+}
+
+/** The URL path selects the Terse API or the actor runtime explicitly. */
+function parseActorEndpoint(value) {
+    const invalid = () => new Error("TERSE_ACTOR_URL must be an HTTP(S) URL ending in /<projectId>/actors or /v1/projects/<projectId>/actors, without credentials, query, or fragment")
+    const url = URL.canParse(value) ? new URL(value) : undefined
+    const match = url && /^\/(?:(sdk|v1)\/projects\/)?([^/]+)\/actors\/?$/.exec(url.pathname)
+    if (!match || !["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw invalid()
+    const projectId = decodeURIComponent(match[2])
+    if (!/^[A-Za-z0-9._-]{1,64}$/.test(projectId) || projectId === "." || projectId === "..") throw invalid()
+    const kind = match[1] === "v1" ? "runtime" : "terse"
+    const project = encodeURIComponent(projectId)
+    return { kind, origin: url.origin, projectId, actorUrl: `${url.origin}${kind === "runtime" ? `/v1/projects/${project}` : `/${project}`}/actors` }
+}
+
+function configuredSetupTimeoutMs() {
+    const configured = globalThis.process?.env?.TERSE_ACTOR_SETUP_TIMEOUT_MS?.trim()
+    if (!configured) return undefined
+    const value = Number(configured)
+    if (!Number.isSafeInteger(value) || value < 1_000 || value > 600_000) {
+        throw new Error("TERSE_ACTOR_SETUP_TIMEOUT_MS must be an integer between 1000 and 600000 milliseconds")
+    }
+    return value
+}

package/templates/typescript/tsconfig.json

@@ -0,0 +1,13 @@
+{
+    // These templates import ./runtime/, which exists only beside generated output.
+    // actorGenerate.test.ts typechecks them there with skipLibCheck disabled.
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "strict": true,
+        "noEmit": true,
+        "skipLibCheck": true
+    },
+    "include": ["*.d.ts"]
+}