@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/plan.js

@@ -0,0 +1,96 @@
+import { InvalidOntology } from "../diagnostics.js";
+import { generatedActionPermissions } from "../permissions.js";
+const DEFAULT_PHRASE = "has";
+function declaredTraversal({ name, relationship, target }) {
+    const pair = relationship.cardinality === "one" ? Object.entries(relationship.on ?? {})[0] : undefined;
+    return {
+        name,
+        kind: relationship.cardinality,
+        target: target ?? "",
+        opposite: relationship.inverse,
+        phrase: relationship.phrase?.[0] ?? DEFAULT_PHRASE,
+        description: relationship.description,
+        ...(pair === undefined ? {} : { match: { source: pair[0], target: pair[1] } }),
+    };
+}
+function inverseTraversals(owner, entities) {
+    return entities.flatMap((source) => source.relationships
+        .filter((candidate) => candidate.target === owner)
+        .map(({ name, relationship }) => {
+        const pair = relationship.cardinality === "one" ? Object.entries(relationship.on ?? {})[0] : undefined;
+        return {
+            name: relationship.inverse,
+            kind: relationship.cardinality === "one"
+                ? "inverseOfOne"
+                : "inverseOfMany",
+            target: source.name,
+            opposite: name,
+            phrase: relationship.phrase?.[1] ?? DEFAULT_PHRASE,
+            description: relationship.description,
+            ...(pair === undefined
+                ? {}
+                : {
+                    match: {
+                        source: pair[1],
+                        target: pair[0],
+                    },
+                }),
+        };
+    }));
+}
+function plannedActions(resolved, generatedActions, report) {
+    if (resolved.entity.definition.source !== undefined) {
+        return [];
+    }
+    const generated = Object.entries(generatedActions(resolved)).map(([name, action]) => ({
+        name,
+        action,
+        generated: true,
+        permissions: generatedActionPermissions(resolved.name, name),
+    }));
+    const authored = resolved.actions.map(({ name, action, permission, writes }) => ({
+        name,
+        action,
+        generated: false,
+        permissions: [permission],
+        ...(writes === undefined ? {} : { writes }),
+    }));
+    const actions = [...generated, ...authored];
+    const names = new Set();
+    for (const { name } of actions) {
+        if (names.has(name)) {
+            report(`${resolved.name}.actions.${name}`, `${name} is both generated and authored.`);
+        }
+        names.add(name);
+    }
+    return actions;
+}
+/**
+ * Plans the routes of a checked ontology. `check` already refuses names that would shadow a route of
+ * the service; this throws {@link InvalidOntology} when a generated action would shadow an authored
+ * one.
+ */
+export function planApi(ontology, generatedActions) {
+    const diagnostics = [];
+    const report = (path, message) => {
+        diagnostics.push({ severity: "error", code: "reserved-name", path, message });
+    };
+    const entities = ontology.entities.map((resolved) => ({
+        name: resolved.name,
+        resolved,
+        traversals: [
+            ...resolved.relationships.map(declaredTraversal),
+            ...inverseTraversals(resolved.name, ontology.entities),
+        ],
+        actions: plannedActions(resolved, (entity) => generatedActions(entity, ontology), report),
+    }));
+    if (diagnostics.length > 0) {
+        throw new InvalidOntology({
+            message: `The ontology service cannot serve this ontology:\n${diagnostics
+                .map((diagnostic) => `${diagnostic.path}: ${diagnostic.message}`)
+                .join("\n")}`,
+            diagnostics,
+        });
+    }
+    return { ontology, entities };
+}

package/dist/service/rate-limit.d.ts

@@ -0,0 +1,22 @@
+import type { HttpServerRequest } from "effect/unstable/http";
+/** Requests a fixed window allows per key, as one service instance counts them. */
+export interface RateLimit {
+    readonly limit: number;
+    readonly windowMs: number;
+    /** Keys tracked at most; expired windows are dropped first, then the oldest. */
+    readonly maxKeys: number;
+}
+export interface RateLimiter {
+    /** Counts one request for `key`: the seconds to wait when it is over the limit, else `undefined`. */
+    readonly take: (key: string, now?: number) => number | undefined;
+}
+/**
+ * A fixed-window counter in this instance's memory. Serverless instances do not share it, so it
+ * slows a client down rather than enforcing an exact limit across the deployment.
+ */
+export declare function fixedWindowLimiter({ limit, windowMs, maxKeys }: RateLimit): RateLimiter;
+/**
+ * The client's address: `x-real-ip`, which Vercel sets, else the first `x-forwarded-for` hop, else
+ * the socket's address. Requests that carry none share one key.
+ */
+export declare function clientAddress(request: HttpServerRequest.HttpServerRequest): string;

package/dist/service/rate-limit.js

@@ -0,0 +1,52 @@
+import { Option } from "effect";
+/**
+ * A fixed-window counter in this instance's memory. Serverless instances do not share it, so it
+ * slows a client down rather than enforcing an exact limit across the deployment.
+ */
+export function fixedWindowLimiter({ limit, windowMs, maxKeys }) {
+    const windows = new Map();
+    function prune(now) {
+        for (const [key, window] of windows) {
+            if (now - window.start >= windowMs) {
+                windows.delete(key);
+            }
+        }
+        for (const key of windows.keys()) {
+            if (windows.size < maxKeys) {
+                break;
+            }
+            windows.delete(key);
+        }
+    }
+    return {
+        take(key, now = Date.now()) {
+            const current = windows.get(key);
+            if (current === undefined || now - current.start >= windowMs) {
+                if (current === undefined && windows.size >= maxKeys) {
+                    prune(now);
+                }
+                windows.set(key, { start: now, count: 1 });
+                return undefined;
+            }
+            current.count += 1;
+            return current.count > limit
+                ? Math.max(1, Math.ceil((current.start + windowMs - now) / 1000))
+                : undefined;
+        },
+    };
+}
+/**
+ * The client's address: `x-real-ip`, which Vercel sets, else the first `x-forwarded-for` hop, else
+ * the socket's address. Requests that carry none share one key.
+ */
+export function clientAddress(request) {
+    const realIp = request.headers["x-real-ip"]?.trim();
+    if (realIp !== undefined && realIp !== "") {
+        return realIp;
+    }
+    const forwarded = request.headers["x-forwarded-for"]?.split(",")[0]?.trim();
+    if (forwarded !== undefined && forwarded !== "") {
+        return forwarded;
+    }
+    return Option.getOrElse(request.remoteAddress ?? Option.none(), () => "unknown");
+}

package/dist/service/record-reads.d.ts

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import { NotFound, PermissionDenied } from "../errors.js";
+import { type QueryResult } from "../query.js";
+import { InvalidQuery } from "../runtime/errors.js";
+import type { StoredRecord } from "../runtime.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { RequestId, WarehouseReadUnavailable } from "./errors.js";
+import type { ApiPlan } from "./plan.js";
+import type { OntologyBackend } from "./runtime-contract.js";
+type Backend = OntologyBackend["Service"];
+type FindInput = Parameters<Backend["find"]>[0];
+type GetInput = Parameters<Backend["get"]>[0];
+type Failure = InvalidQuery | NotFound | PermissionDenied | WarehouseReadUnavailable;
+type Read<A> = Effect.Effect<A, Failure, CurrentPrincipal | RequestId>;
+export interface RecordReads {
+    readonly get: (input: GetInput) => Read<StoredRecord>;
+    readonly find: (input: FindInput) => Read<QueryResult<StoredRecord>>;
+}
+/** Composes the existing scoped stored reader with observations, without moving either store. */
+export declare function recordReads(backend: Backend, plan: ApiPlan): RecordReads;
+export {};

package/dist/service/record-reads.js

@@ -0,0 +1,155 @@
+import { Effect, Option, Schema } from "effect";
+import { NotFound, PermissionDenied } from "../errors.js";
+import { readScope } from "../permissions.js";
+import { entityQuerySchema, includedRelationships, } from "../query.js";
+import { InvalidQuery } from "../runtime/errors.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { RequestId, schemaIssues, WarehouseReadUnavailable } from "./errors.js";
+import { WarehouseQueries } from "./warehouse-platform.js";
+import { compileWarehouseQuery } from "./warehouse-query.js";
+/** Composes the existing scoped stored reader with observations, without moving either store. */
+export function recordReads(backend, plan) {
+    const { manifest } = plan.ontology;
+    const entities = new Map(manifest.entities.map((entity) => [entity.name, entity]));
+    const planned = new Map(plan.entities.map((entity) => [entity.name, entity]));
+    const invalid = (entity, message) => new InvalidQuery({
+        entity,
+        message,
+        issues: [{ path: [], message }],
+    });
+    const validate = (entity, query) => Schema.decodeUnknownEffect(entityQuerySchema(manifest, entity, true))(query, {
+        errors: "all",
+    }).pipe(Effect.mapError((error) => new InvalidQuery({
+        entity,
+        message: "The query does not match the entity.",
+        issues: schemaIssues(error.issue),
+    })));
+    const baseFind = (input) => Effect.gen(function* () {
+        const entity = entities.get(input.entity);
+        if (entity?.source === undefined) {
+            return yield* backend.find(input);
+        }
+        const principal = yield* CurrentPrincipal;
+        if (readScope(entity.name, principal) !== undefined) {
+            return yield* new PermissionDenied({
+                permission: `${entity.name}:read`,
+                message: "Warehouse records do not support scoped warehouse read grants.",
+            });
+        }
+        const query = yield* validate(entity.name, input.query);
+        const transport = yield* Effect.serviceOption(WarehouseQueries);
+        if (Option.isNone(transport)) {
+            return yield* new WarehouseReadUnavailable({ reason: "not_configured" });
+        }
+        const statement = yield* Effect.try({
+            try: () => compileWarehouseQuery(manifest, entity, query),
+            catch: (error) => error instanceof InvalidQuery
+                ? error
+                : new WarehouseReadUnavailable({ reason: "upstream", cause: error }),
+        });
+        const requestId = yield* RequestId;
+        const rows = yield* transport.value({ statement, requestId, principalId: principal.id });
+        return yield* Effect.try({
+            try: () => statement.decode(rows),
+            catch: (error) => error instanceof InvalidQuery
+                ? error
+                : new WarehouseReadUnavailable({ reason: "upstream", cause: error }),
+        });
+    });
+    return {
+        get: (input) => Effect.gen(function* () {
+            if (entities.get(input.entity)?.source === undefined) {
+                return yield* backend.get(input);
+            }
+            const result = yield* baseFind({
+                entity: input.entity,
+                query: { where: { id: input.id }, limit: 1 },
+                ...(input.reader === undefined ? {} : { reader: input.reader }),
+            });
+            const record = result.items[0];
+            if (record === undefined) {
+                return yield* new NotFound({
+                    entity: input.entity,
+                    id: input.id,
+                    message: "The warehouse record was not found.",
+                });
+            }
+            return record;
+        }),
+        find: (input) => Effect.gen(function* () {
+            const definition = planned.get(input.entity);
+            const names = includedRelationships(input.query.include);
+            const matched = definition?.traversals.filter((traversal) => names.includes(traversal.name) && traversal.match !== undefined) ?? [];
+            if (matched.length === 0) {
+                return yield* baseFind(input);
+            }
+            const query = yield* validate(input.entity, input.query);
+            const physical = names.filter((name) => !matched.some((link) => link.name === name));
+            const select = query.select === undefined
+                ? undefined
+                : [...new Set([...query.select, ...matched.map((link) => link.match.source)])];
+            const page = yield* baseFind({
+                ...input,
+                query: {
+                    ...query,
+                    include: physical,
+                    ...(select === undefined ? {} : { select }),
+                },
+            });
+            let items = [...page.items];
+            for (const link of matched) {
+                const match = link.match;
+                const candidates = items
+                    .map((item) => item[match.source])
+                    .filter((value) => value !== null && value !== undefined);
+                if (candidates.some((value) => typeof value !== "string" &&
+                    typeof value !== "number" &&
+                    typeof value !== "boolean")) {
+                    return yield* invalid(input.entity, "A relationship key must be a scalar value.");
+                }
+                const values = [
+                    ...new Set(candidates.filter((value) => typeof value === "string" ||
+                        typeof value === "number" ||
+                        typeof value === "boolean")),
+                ];
+                const grouped = new Map();
+                if (values.length > 0) {
+                    const related = yield* baseFind({
+                        entity: link.target,
+                        query: { where: { [match.target]: { in: values } }, limit: 200 },
+                        ...(input.reader === undefined ? {} : { reader: input.reader }),
+                    });
+                    if (related.nextCursor !== null) {
+                        return yield* invalid(input.entity, "Related records exceed a bounded include; use the paged relationship route.");
+                    }
+                    for (const record of related.items) {
+                        const key = record[match.target];
+                        if (key !== null && key !== undefined) {
+                            const group = grouped.get(key) ?? [];
+                            group.push(record);
+                            grouped.set(key, group);
+                        }
+                    }
+                }
+                if (link.kind === "one" && [...grouped.values()].some((group) => group.length > 1)) {
+                    return yield* invalid(input.entity, "The target key of a to-one relationship is not unique.");
+                }
+                items = items.map((record) => ({
+                    ...record,
+                    [link.name]: link.kind === "one"
+                        ? (grouped.get(record[match.source])?.[0] ?? null)
+                        : (grouped.get(record[match.source]) ?? []),
+                }));
+            }
+            if (query.select !== undefined) {
+                const selected = new Set(["id", ...query.select, ...names]);
+                items = items.map((record) => Object.fromEntries(Object.entries(record).filter(([name]) => selected.has(name))));
+            }
+            return {
+                ...page,
+                items,
+                ...(query.select === undefined ? {} : { projected: true }),
+            };
+        }),
+    };
+}

package/dist/service/replication.d.ts

@@ -0,0 +1,5 @@
+import { Effect } from "effect";
+import type { OntologyEnvironment } from "./config.js";
+export type ReplicationKick = (identity: string | undefined) => Effect.Effect<void>;
+/** Coalesce best-effort wakes without adding network latency to committed actions. Durable recovery owns retries. */
+export declare function deployedReplication(environment: OntologyEnvironment, fetchImpl?: typeof fetch): ReplicationKick;

package/dist/service/replication.js

@@ -0,0 +1,39 @@
+import { Effect } from "effect";
+/** Coalesce best-effort wakes without adding network latency to committed actions. Durable recovery owns retries. */
+export function deployedReplication(environment, fetchImpl = fetch) {
+    if (environment.deployment?.target === "preview") {
+        return () => Effect.void;
+    }
+    let inFlight = false;
+    let nextWakeAt = 0;
+    return (identity) => {
+        if (!identity) {
+            return Effect.void;
+        }
+        return Effect.suspend(() => {
+            if (inFlight || Date.now() < nextWakeAt) {
+                return Effect.void;
+            }
+            inFlight = true;
+            nextWakeAt = Date.now() + 1000;
+            return Effect.tryPromise(async () => {
+                const response = await fetchImpl(`${environment.segmentstreamUrl}/api/internal/v1/workspaces/` +
+                    `${encodeURIComponent(environment.workspaceId)}/ontology/replication/drain`, {
+                    method: "POST",
+                    redirect: "error",
+                    signal: AbortSignal.timeout(5000),
+                    headers: {
+                        "x-segmentstream-runtime-identity": identity,
+                        "x-segmentstream-organization-id": environment.organizationId,
+                    },
+                });
+                await response.body?.cancel();
+                if (!response.ok) {
+                    throw new Error(`Replication wake-up returned HTTP ${response.status}.`);
+                }
+            }).pipe(Effect.catchCause((cause) => Effect.logWarning("ontology.replication.deferred", cause)), Effect.ensuring(Effect.sync(() => {
+                inFlight = false;
+            })), Effect.forkDetach, Effect.asVoid);
+        });
+    };
+}