@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/storage/operator.js

@@ -0,0 +1,30 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import { Effect, Redacted } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { postgresTls } from "../runtime/postgres-tls.js";
+import { maintainBlobStorage } from "./maintenance.js";
+import { neonBlobProvider } from "./neon.js";
+import { BlobStorageError } from "./provider.js";
+/** Scheduler capability that survives removal of blob declarations. Never reads file contents. */
+export function runBlobStorageMaintenance(input) {
+    const limit = input.limit ?? 100;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+        return Effect.fail(new BlobStorageError({ operation: "maintenance.limit" }));
+    }
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const [tables] = yield* sql `
+      SELECT to_regclass('public._blob_uploads')::text AS uploads
+    `;
+        if (!tables?.uploads) {
+            return { removed: 0, hasMore: false };
+        }
+        const provider = yield* Effect.acquireRelease(Effect.sync(() => neonBlobProvider(Redacted.value(input.binding))), (provider) => Effect.sync(() => provider.close?.()));
+        return yield* maintainBlobStorage(sql, provider, limit);
+    }).pipe(Effect.provide(PgClient.layer({
+        url: input.databaseUrl,
+        ssl: postgresTls(input.databaseUrl),
+        maxConnections: 1,
+        applicationName: "segmentstream-ontology-maintenance",
+    })), Effect.scoped);
+}

package/dist/storage/provider.d.ts

@@ -0,0 +1,93 @@
+import { Context, Schema, type Effect } from "effect";
+import { type DeploymentObservation } from "../deployment.js";
+/** Validated deployment binding, independent of the action and browser contracts. */
+export declare const BlobStorageBinding: Schema.Struct<{
+    readonly projectId: Schema.String;
+    readonly branchId: Schema.String;
+    /** Required on preview bindings, so a copied production binding fails closed. */
+    readonly deploymentId: Schema.optionalKey<Schema.String>;
+    /** Preview source branch fence, supplied from the provisioner's verified parent. */
+    readonly productionBranchId: Schema.optionalKey<Schema.String>;
+    readonly endpoint: Schema.String;
+    readonly region: Schema.String;
+    readonly bucket: Schema.Literal<"ontology-files">;
+    readonly accessKeyId: Schema.String;
+    readonly secretAccessKey: Schema.String;
+    readonly quotaBytes: Schema.Int;
+}>;
+export type BlobStorageBinding = typeof BlobStorageBinding.Type;
+/** A copied production binding is never rebound or used by a preview runtime. */
+export declare function validateDeploymentStorage(binding: BlobStorageBinding, deployment?: DeploymentObservation): void;
+declare const BlobStorageError_base: Schema.Class<BlobStorageError, Schema.TaggedStruct<"BlobStorageError", {
+    readonly operation: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Unknown>;
+    /** The provider explicitly refused initiation; no multipart upload was created. */
+    readonly initiationRejected: Schema.optionalKey<Schema.Boolean>;
+}>, import("effect/Cause").YieldableError>;
+export declare class BlobStorageError extends BlobStorageError_base {
+}
+export interface TransferGrant {
+    readonly url: string;
+    readonly method: "GET" | "PUT";
+    readonly headers: Readonly<Record<string, string>>;
+    readonly expiresAt: string;
+}
+export interface StoredObject {
+    readonly size: number;
+    readonly contentType: string;
+    readonly sessionId: string;
+}
+declare const BlobProvider_base: Context.ServiceClass<BlobProvider, "@segmentstream/ontology/BlobProvider", {
+    readonly binding: BlobStorageBinding;
+    readonly close?: () => void;
+    readonly initiate: (input: {
+        key: string;
+        filename: string;
+        contentType: string;
+        sessionId: string;
+    }) => Effect.Effect<string, BlobStorageError>;
+    readonly signPart: (input: {
+        key: string;
+        uploadId: string;
+        partNumber: number;
+        size: number;
+    }) => Effect.Effect<TransferGrant, BlobStorageError>;
+    readonly parts: (input: {
+        key: string;
+        uploadId: string;
+    }) => Effect.Effect<ReadonlyArray<{
+        number: number;
+        size: number;
+        etag: string;
+    }>, BlobStorageError>;
+    readonly complete: (input: {
+        key: string;
+        uploadId: string;
+        parts: ReadonlyArray<{
+            number: number;
+            etag: string;
+        }>;
+    }) => Effect.Effect<void, BlobStorageError>;
+    readonly inspect: (key: string) => Effect.Effect<StoredObject | undefined, BlobStorageError>;
+    /** Hash immutable content without buffering it. */
+    readonly sha256: (key: string, size: number) => Effect.Effect<string, BlobStorageError>;
+    readonly readPrefix: (key: string) => Effect.Effect<Uint8Array, BlobStorageError>;
+    /** The whole object, at most `maxBytes`; for verifying an agent attachment's digest. */
+    readonly read: (key: string, maxBytes: number) => Effect.Effect<Uint8Array, BlobStorageError>;
+    readonly download: (input: {
+        key: string;
+        filename: string;
+        contentType: string;
+        inline: boolean;
+    }) => Effect.Effect<TransferGrant, BlobStorageError>;
+    readonly abort: (input: {
+        key: string;
+        uploadId: string;
+    }) => Effect.Effect<void, BlobStorageError>;
+    readonly remove: (key: string) => Effect.Effect<void, BlobStorageError>;
+    readonly pending: (key: string) => Effect.Effect<ReadonlyArray<string>, BlobStorageError>;
+}>;
+/** Private provider capability. Actions never receive storage credentials or this service. */
+export declare class BlobProvider extends BlobProvider_base {
+}
+export {};

package/dist/storage/provider.js

@@ -0,0 +1,36 @@
+import { Context, Schema } from "effect";
+import { DeploymentAdmissionError } from "../deployment.js";
+/** Validated deployment binding, independent of the action and browser contracts. */
+export const BlobStorageBinding = Schema.Struct({
+    projectId: Schema.String,
+    branchId: Schema.String,
+    /** Required on preview bindings, so a copied production binding fails closed. */
+    deploymentId: Schema.optionalKey(Schema.String),
+    /** Preview source branch fence, supplied from the provisioner's verified parent. */
+    productionBranchId: Schema.optionalKey(Schema.String),
+    endpoint: Schema.String,
+    region: Schema.String,
+    bucket: Schema.Literal("ontology-files"),
+    accessKeyId: Schema.String,
+    secretAccessKey: Schema.String,
+    quotaBytes: Schema.Int.check(Schema.isGreaterThan(0)),
+});
+/** A copied production binding is never rebound or used by a preview runtime. */
+export function validateDeploymentStorage(binding, deployment) {
+    if (deployment?.target === "preview" &&
+        (binding.deploymentId !== deployment.deploymentId ||
+            !binding.productionBranchId ||
+            binding.productionBranchId === binding.branchId)) {
+        throw new DeploymentAdmissionError("preview_storage_binding_invalid");
+    }
+}
+export class BlobStorageError extends Schema.TaggedError()("BlobStorageError", {
+    operation: Schema.String,
+    cause: Schema.optionalKey(Schema.Unknown),
+    /** The provider explicitly refused initiation; no multipart upload was created. */
+    initiationRejected: Schema.optionalKey(Schema.Boolean),
+}) {
+}
+/** Private provider capability. Actions never receive storage credentials or this service. */
+export class BlobProvider extends Context.Service()("@segmentstream/ontology/BlobProvider") {
+}

package/dist/storage/sessions.d.ts

@@ -0,0 +1,184 @@
+import { Effect, Schema } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { type SqlError } from "effect/unstable/sql/SqlError";
+import { ActionRejected, Conflict, NotFound } from "../errors.js";
+import { Files } from "../files.js";
+import type { FileInvocation } from "./file-access.js";
+import type { Ontology } from "../ontology.js";
+import type { Principal } from "../runtime.js";
+import { BlobStorageError, type BlobProvider } from "./provider.js";
+export declare const BeginUpload: Schema.encodeKeys<Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly property: Schema.String;
+    readonly action: Schema.String;
+    readonly recordId: Schema.optionalKey<Schema.String>;
+    readonly createIntent: Schema.optionalKey<Schema.String>;
+    readonly idempotencyKey: Schema.optionalKey<Schema.String>;
+    readonly filename: Schema.String;
+    readonly contentType: Schema.String;
+    readonly size: Schema.Int;
+}>, {
+    readonly recordId: "record_id";
+    readonly createIntent: "create_intent";
+    readonly idempotencyKey: "idempotency_key";
+    readonly contentType: "content_type";
+}>;
+export type BeginUpload = typeof BeginUpload.Type;
+export declare const UploadView: Schema.encodeKeys<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly state: Schema.String;
+    readonly expiresAt: Schema.String;
+    readonly ticket: Schema.optionalKey<Schema.decodeTo<Schema.Struct<{
+        readonly uploadId: Schema.String;
+    }>, Schema.Struct<{
+        readonly upload_id: Schema.String;
+    }>, never, never>>;
+}>, {
+    readonly expiresAt: "expires_at";
+}>;
+export declare const OpenUpload: Schema.encodeKeys<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly state: Schema.String;
+    readonly filename: Schema.String;
+    readonly contentType: Schema.String;
+    readonly size: Schema.Int;
+    readonly entity: Schema.String;
+    readonly property: Schema.String;
+    readonly action: Schema.String;
+    readonly recordId: Schema.NullOr<Schema.String>;
+    readonly createIntent: Schema.NullOr<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly expiresAt: Schema.String;
+    readonly awaitingAction: Schema.Boolean;
+}>, {
+    readonly contentType: "content_type";
+    readonly recordId: "record_id";
+    readonly createIntent: "create_intent";
+    readonly createdAt: "created_at";
+    readonly expiresAt: "expires_at";
+    readonly awaitingAction: "awaiting_action";
+}>;
+export declare const OpenUploads: Schema.Struct<{
+    readonly uploads: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly state: Schema.String;
+        readonly filename: Schema.String;
+        readonly contentType: Schema.String;
+        readonly size: Schema.Int;
+        readonly entity: Schema.String;
+        readonly property: Schema.String;
+        readonly action: Schema.String;
+        readonly recordId: Schema.NullOr<Schema.String>;
+        readonly createIntent: Schema.NullOr<Schema.String>;
+        readonly createdAt: Schema.String;
+        readonly expiresAt: Schema.String;
+        readonly awaitingAction: Schema.Boolean;
+    }>, {
+        readonly contentType: "content_type";
+        readonly recordId: "record_id";
+        readonly createIntent: "create_intent";
+        readonly createdAt: "created_at";
+        readonly expiresAt: "expires_at";
+        readonly awaitingAction: "awaiting_action";
+    }>>;
+    readonly pending: Schema.Int;
+    readonly max: Schema.Int;
+}>;
+export declare const TransferGrant: Schema.encodeKeys<Schema.Struct<{
+    readonly url: Schema.String;
+    readonly method: Schema.Literals<readonly ["GET", "PUT"]>;
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+    readonly expiresAt: Schema.String;
+}>, {
+    readonly expiresAt: "expires_at";
+}>;
+export declare const DownloadRequest: Schema.encodeKeys<Schema.Struct<{
+    readonly revisionId: Schema.optionalKey<Schema.String>;
+    readonly inline: Schema.optionalKey<Schema.Boolean>;
+}>, {
+    readonly revisionId: "revision_id";
+}>;
+/** Persisted phases surround every provider call; no external I/O holds a database transaction. */
+export declare function blobRuntime(ontology: Ontology, sql: SqlClient.SqlClient, provider: BlobProvider["Service"], fetchImpl?: typeof fetch): {
+    begin: (input: BeginUpload, principal: Principal) => Effect.Effect<{
+        ticket?: {
+            uploadId: string;
+        } | undefined;
+        id: string;
+        state: string;
+        expiresAt: string;
+    }, ActionRejected | import("../errors.js").PermissionDenied | Conflict | NotFound | SqlError | BlobStorageError, never>;
+    list: (principal: Principal) => Effect.Effect<{
+        uploads: {
+            id: string;
+            state: string;
+            filename: string;
+            contentType: string;
+            size: number;
+            entity: string;
+            property: string;
+            action: string;
+            recordId: string | null;
+            createIntent: string | null;
+            createdAt: string;
+            expiresAt: string;
+            awaitingAction: boolean;
+        }[];
+        pending: number;
+        max: number;
+    }, SqlError, never>;
+    status: (id: string, principal: Principal) => Effect.Effect<{
+        ticket?: {
+            uploadId: string;
+        } | undefined;
+        id: string;
+        state: string;
+        expiresAt: string;
+    }, import("../errors.js").PermissionDenied | Conflict | NotFound | SqlError, never>;
+    target: (id: string, principal: Principal) => Effect.Effect<{
+        entity: string;
+        action: string;
+        property: string;
+        recordId: string | null;
+        createIntent: string | null;
+    }, import("../errors.js").PermissionDenied | Conflict | NotFound | SqlError, never>;
+    part: (id: string, principal: Principal) => Effect.Effect<import("./provider.js").TransferGrant, import("../errors.js").PermissionDenied | Conflict | NotFound | SqlError | BlobStorageError, never>;
+    complete: (id: string, principal: Principal) => Effect.Effect<{
+        ticket?: {
+            uploadId: string;
+        } | undefined;
+        id: string;
+        state: string;
+        expiresAt: string;
+    }, ActionRejected | import("../errors.js").PermissionDenied | Conflict | NotFound | SqlError | BlobStorageError, never>;
+    cancel: (id: string, principal: Principal) => Effect.Effect<{
+        ticket?: {
+            uploadId: string;
+        } | undefined;
+        id: string;
+        state: string;
+        expiresAt: string;
+    }, import("../errors.js").PermissionDenied | Conflict | NotFound | SqlError, never>;
+    download: (entityName: string, recordId: string, propertyName: string, input: {
+        readonly inline?: boolean | undefined;
+        readonly revisionId?: string | undefined;
+    }, principal: Principal) => Effect.Effect<import("./provider.js").TransferGrant, import("../errors.js").PermissionDenied | NotFound | SqlError | BlobStorageError, never>;
+    downloadFile: (entityName: string, recordId: string, propertyName: string, input: {
+        readonly inline?: boolean | undefined;
+        readonly revisionId?: string | undefined;
+    }, principal: Principal) => Effect.Effect<{
+        file: {
+            id: string;
+            entity: string;
+            property: string;
+            revision_id: string;
+            filename: string;
+            content_type: string;
+            size: number;
+            sha256: string;
+        };
+        download: import("./provider.js").TransferGrant;
+    }, import("../errors.js").PermissionDenied | NotFound | SqlError | BlobStorageError, never>;
+    files: (invocation: FileInvocation) => Files["Service"];
+};
+export type BlobRuntime = Omit<ReturnType<typeof blobRuntime>, "target" | "files" | "list"> & Partial<Pick<ReturnType<typeof blobRuntime>, "target" | "files" | "list">>;