@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/errors.js

@@ -0,0 +1,704 @@
+import { Cause, Context, Effect, Option, Predicate, Schema, SchemaIssue } from "effect";
+import { HttpServerResponse } from "effect/unstable/http";
+import { HttpApiError } from "effect/unstable/httpapi";
+import { BatchErrorDetails, LimitErrorDetails, } from "../errors.js";
+import { DeploymentAdmissionError } from "../deployment.js";
+import { suggestionDetail } from "./name-suggestions.js";
+/** The correlation id of the current request, in every error body and the `x-request-id` header. */
+export class RequestId extends Context.Service()("@segmentstream/ontology/RequestId") {
+}
+const Issues = Schema.Array(Schema.Struct({
+    path: Schema.Array(Schema.Union([Schema.String, Schema.Number])),
+    message: Schema.String,
+}));
+/** The action's input failed validation and the request was not `validateOnly`. */
+export class InvalidActionInput extends Schema.TaggedError()("InvalidActionInput", { issues: Issues }) {
+}
+/** The body of an action request is not `{ input, options? }`. */
+export class InvalidRequestBody extends Schema.TaggedError()("InvalidRequestBody", {
+    reason: Schema.Literals(["invalid_json", "invalid_request", "unsupported_media_type"]),
+    issues: Issues,
+}) {
+}
+/** A client asked `POST /api/ontology/sign-in/check` too often; it may ask again after this. */
+export class SignInCheckLimited extends Schema.TaggedError()("SignInCheckLimited", { retryAfterSeconds: Schema.Number }) {
+}
+/** A metric query the ontology cannot answer; the reason is written for the caller. */
+export class InvalidMetricQuery extends Schema.TaggedError()("InvalidMetricQuery", { reason: Schema.String }) {
+}
+/** The caller lacks `<entity>:read` on entities a metric query reads: every such permission. */
+export class ReadDenied extends Schema.TaggedError()("ReadDenied", {
+    permissions: Schema.Array(Schema.String),
+}) {
+}
+/**
+ * Why a scope cannot be applied to a metric query: it follows a path from `me` (`me_path`), is too
+ * large to send (`too_large`), SegmentStream cannot plan it in the warehouse (`unplannable`), or
+ * SegmentStream did not confirm it applied it (`unconfirmed`). A code, so that a workspace words it.
+ */
+export const ScopedMetricQueryReason = Schema.Literals([
+    "me_path",
+    "too_large",
+    "unplannable",
+    "unconfirmed",
+]);
+/**
+ * The caller reads an entity a metric query touches only within a scope the query cannot apply:
+ * answering would count or sum rows the caller's lists leave out. `reason` says why, when known.
+ */
+export class ScopedMetricQueryUnavailable extends Schema.TaggedError()("ScopedMetricQueryUnavailable", { entity: Schema.String, reason: Schema.optional(ScopedMetricQueryReason) }) {
+}
+/** The deployment has no workspace app credential: previews and local development. */
+export class MetricQueriesUnavailable extends Schema.TaggedError()("MetricQueriesUnavailable", {}) {
+}
+/** A warehouse observation could not be read; no database record is substituted. */
+export class WarehouseReadUnavailable extends Schema.TaggedError()("WarehouseReadUnavailable", {
+    reason: Schema.Literals(["not_configured", "upstream", "limited"]),
+    retryAfterSeconds: Schema.optionalKey(Schema.Number),
+    cause: Schema.optionalKey(Schema.Unknown),
+}) {
+}
+/** A principal ran more metric queries than its window allows; it may run more after this. */
+export class MetricQueryLimited extends Schema.TaggedError()("MetricQueryLimited", {
+    retryAfterSeconds: Schema.Number,
+}) {
+}
+/**
+ * SegmentStream did not answer a metric query usably, or its answer faults the deployment rather than
+ * the caller. The operator log keeps the details; the caller learns only the reason.
+ */
+export class MetricQueryUpstreamUnavailable extends Schema.TaggedError()("MetricQueryUpstreamUnavailable", {
+    reason: Schema.Literals([
+        "unreachable",
+        "timeout",
+        "invalid_response",
+        "credential_rejected",
+        "upstream_misconfigured",
+    ]),
+    status: Schema.optionalKey(Schema.Number),
+}) {
+}
+const UPSTREAM_DETAILS = {
+    unreachable: "SegmentStream could not be reached. Try again shortly.",
+    timeout: "SegmentStream did not answer in time. Try again shortly.",
+    invalid_response: "SegmentStream answered with an unexpected response.",
+    credential_rejected: "SegmentStream refused the deployment's credential.",
+    upstream_misconfigured: "SegmentStream does not serve metric queries for this deployment.",
+};
+/** `a`, `a and b`, `a, b and c`. */
+function listed(values) {
+    return values.length <= 1
+        ? values.join("")
+        : `${values.slice(0, -1).join(", ")} and ${values.at(-1)}`;
+}
+/** Only the declared safe locations cross a transport, even for structurally tagged failures. */
+function batchDetails(error) {
+    const batch = error.batch;
+    if (!Schema.is(BatchErrorDetails)(batch)) {
+        return {};
+    }
+    return {
+        batch: {
+            indices: batch.indices,
+            ...(batch.fields === undefined ? {} : { fields: batch.fields }),
+        },
+    };
+}
+/** The refusing limit and its numbers, in wire casing. */
+function limitDetails(error) {
+    const limit = error.limit;
+    if (!Schema.is(LimitErrorDetails)(limit)) {
+        return {};
+    }
+    switch (limit.kind) {
+        case "storage_quota":
+            return {
+                limit: {
+                    kind: limit.kind,
+                    used_bytes: limit.usedBytes,
+                    requested_bytes: limit.requestedBytes,
+                    quota_bytes: limit.quotaBytes,
+                },
+            };
+        case "pending_uploads":
+            return {
+                limit: {
+                    kind: limit.kind,
+                    pending: limit.pending,
+                    max: limit.max,
+                    ...(limit.uploads === undefined
+                        ? {}
+                        : {
+                            uploads: limit.uploads.map((upload) => ({
+                                id: upload.id,
+                                filename: upload.filename,
+                                expires_at: upload.expiresAt,
+                            })),
+                        }),
+                },
+            };
+        case "member_attachments":
+            return { limit: { kind: limit.kind, live: limit.live, max: limit.max } };
+    }
+}
+export function toServerResponse(response) {
+    return HttpServerResponse.jsonUnsafe(errorBodyForWire(response.body), {
+        status: response.status,
+        ...(response.headers !== undefined ? { headers: response.headers } : {}),
+    });
+}
+export function errorBodyForWire(body) {
+    const { requestId, ...rest } = body;
+    return { ...rest, request_id: requestId };
+}
+/** Issues of a schema failure, as `[{ path, message }]`. */
+export function schemaIssues(issue) {
+    const formatted = SchemaIssue.makeFormatterStandardSchemaV1()(issue);
+    return formatted.issues.map((candidate) => ({
+        path: (candidate.path ?? []).map((segment) => {
+            const key = typeof segment === "object" && segment !== null ? segment.key : segment;
+            return typeof key === "number" ? key : String(key);
+        }),
+        message: candidate.message,
+    }));
+}
+const REQUEST_PARTS = {
+    Params: "The path is invalid.",
+    Query: "The query parameters are invalid.",
+    Payload: "The request body is invalid.",
+    Headers: "The request headers are invalid.",
+};
+function isJsonParseFailure(issue) {
+    return (issue._tag === "InvalidValue" && issue.annotations?.message === "Expected a valid JSON body");
+}
+/**
+ * `challenge` is the `WWW-Authenticate` value; the MCP server's names its OAuth metadata, which is
+ * how a client learns where members authorize it.
+ */
+export function unauthorized(requestId, detail, challenge = 'Bearer realm="ontology"') {
+    return {
+        status: 401,
+        body: { error: "unauthorized", detail, requestId },
+        headers: { "www-authenticate": challenge },
+    };
+}
+/**
+ * The token is valid but the `invited` sign-in policy turns its holder away: nobody invited them.
+ * The detail is written for the person, since the app shows it.
+ */
+export function notInvited(requestId) {
+    return {
+        status: 403,
+        body: { error: "not_invited", detail: "Ask your administrator for an invitation.", requestId },
+    };
+}
+/**
+ * A request that changes something came with the session cookie but not from the app's own pages.
+ * The cookie rides along with any request to the app's domain, so only its origin can vouch for it.
+ */
+export function crossOriginSession(requestId) {
+    return {
+        status: 403,
+        body: {
+            error: "forbidden",
+            detail: "The session cookie only authenticates requests from the app's own pages; send a bearer token.",
+            requestId,
+        },
+    };
+}
+/** The caller is authenticated but may not do this; the detail says why. */
+export function forbidden(requestId, detail) {
+    return { status: 403, body: { error: "forbidden", detail, requestId } };
+}
+/** A client asked too often; it may ask again after `retryAfterSeconds`. */
+export function rateLimited(requestId, detail, retryAfterSeconds) {
+    return {
+        status: 429,
+        body: { error: "rate_limited", detail, requestId },
+        headers: { "retry-after": String(retryAfterSeconds) },
+    };
+}
+/** The resource does not exist, or not for this caller; the detail says what to do. */
+export function notFound(requestId, detail) {
+    return { status: 404, body: { error: "not_found", detail, requestId } };
+}
+export function unavailable(requestId) {
+    return {
+        status: 503,
+        body: {
+            error: "service_unavailable",
+            detail: "Sign-in could not be verified right now. Try again shortly.",
+            requestId,
+        },
+    };
+}
+/** File storage failed. The caller retries the same request; operators still log the cause. */
+export function storageUnavailable(requestId) {
+    return {
+        status: 503,
+        body: {
+            error: "storage_unavailable",
+            detail: "File storage did not complete the request. Retry the same request.",
+            requestId,
+            retryable: true,
+        },
+        headers: { "retry-after": "5" },
+    };
+}
+/** A failure of the file storage provider, which is answered as retryable but still logged. */
+export function isStorageFailure(error) {
+    return Predicate.isTagged(error, "BlobStorageError");
+}
+export function internalError(requestId) {
+    return {
+        status: 500,
+        body: {
+            error: "internal_error",
+            detail: "The request failed. Quote the request id when you report it.",
+            requestId,
+        },
+    };
+}
+export function routeNotFound(requestId, suggestions = []) {
+    return {
+        status: 404,
+        body: {
+            error: "not_found",
+            detail: suggestionDetail("There is no such ontology route.", suggestions),
+            requestId,
+            ...(suggestions.length === 0 ? {} : { suggestions }),
+        },
+    };
+}
+/**
+ * A connection call failed and `prepare` did not handle it; nothing was written. A refusal by the
+ * platform (`not_granted`, `invalid_request`) is a fault of the deployment: it is not expected, so
+ * it is logged with its cause and answered as a 500. The
+ * caller learns which connection failed and why, never the provider's or the proxy's message.
+ */
+function connectionFailure(error, requestId) {
+    const connection = error.connection;
+    switch (error.reason) {
+        case "authorization_required":
+            return {
+                status: 409,
+                body: {
+                    error: "connection_authorization_required",
+                    detail: `Configure or authorize the ${connection} connection in SegmentStream.`,
+                    requestId,
+                    connection,
+                },
+            };
+        case "not_deployed":
+            return {
+                status: 409,
+                body: {
+                    error: "connections_not_deployed",
+                    detail: `Deploy the workspace connections with the ${connection} connection.`,
+                    requestId,
+                    connection,
+                },
+            };
+        case "unavailable":
+        case "timeout":
+            return {
+                status: 503,
+                body: {
+                    error: "connection_unavailable",
+                    detail: `The ${connection} connection is temporarily unavailable. Try again.`,
+                    requestId,
+                    connection,
+                    retryable: true,
+                },
+            };
+        case "refused":
+            return {
+                status: 503,
+                body: {
+                    error: "connection_refused",
+                    detail: `The ${connection} provider refused the request.`,
+                    requestId,
+                    connection,
+                    retryable: false,
+                },
+            };
+        case "invalid_response":
+            return {
+                status: 502,
+                body: {
+                    error: "connection_response_invalid",
+                    detail: `The ${connection} provider answered with an unexpected response.`,
+                    requestId,
+                    connection,
+                },
+            };
+        default:
+            return undefined;
+    }
+}
+/**
+ * The response for an expected failure, or `undefined` for anything else. Messages written for the
+ * caller (an action's rejection, schema issues about the request) are returned; everything else
+ * gets a fixed detail.
+ */
+export function expectedFailure(error, requestId) {
+    if (Predicate.isTagged(error, "DeploymentInterrupted")) {
+        const failure = error;
+        const identifiers = Object.fromEntries(Object.entries({
+            served_hash: failure.servedHash,
+            applied_hash: failure.appliedHash,
+            served_deployment_id: failure.servedDeploymentId,
+            applied_deployment_id: failure.appliedDeploymentId,
+        }).filter(([, value]) => typeof value === "string" && /^[A-Za-z0-9_.:-]{1,200}$/.test(value)));
+        return {
+            status: 409,
+            body: {
+                error: "deployment_interrupted",
+                detail: "deployment_interrupted",
+                requestId,
+                retryable: false,
+                ...identifiers,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "DeploymentSwitching")) {
+        const failure = error;
+        const retryAfter = Number.isFinite(failure.retryAfter)
+            ? Math.min(30, Math.max(1, Math.ceil(failure.retryAfter)))
+            : 5;
+        return {
+            status: 503,
+            body: {
+                error: "deployment_switching",
+                detail: "deployment_switching",
+                requestId,
+                retryable: true,
+                ...(typeof failure.generation === "string" &&
+                    /^[A-Za-z0-9_.:-]{1,200}$/.test(failure.generation)
+                    ? { generation: failure.generation }
+                    : {}),
+            },
+            headers: { "retry-after": String(retryAfter) },
+        };
+    }
+    if (error instanceof DeploymentAdmissionError) {
+        return {
+            status: error.status,
+            body: {
+                error: error.code,
+                detail: error.code,
+                requestId,
+                ...(error.capability ? { capability: error.capability } : {}),
+            },
+        };
+    }
+    if (HttpApiError.HttpApiSchemaError.is(error)) {
+        const issue = error.cause.issue;
+        if (isJsonParseFailure(issue)) {
+            return {
+                status: 400,
+                body: { error: "invalid_json", detail: "The request body is not valid JSON.", requestId },
+            };
+        }
+        return {
+            status: 400,
+            body: {
+                error: "invalid_request",
+                detail: REQUEST_PARTS[error.kind] ?? "The request is invalid.",
+                requestId,
+                issues: schemaIssues(issue),
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "InvalidRequestBody")) {
+        const { reason, issues } = error;
+        if (reason === "invalid_json") {
+            return {
+                status: 400,
+                body: { error: "invalid_json", detail: "The request body is not valid JSON.", requestId },
+            };
+        }
+        if (reason === "unsupported_media_type") {
+            return {
+                status: 415,
+                body: { error: "unsupported_media_type", detail: "Send application/json.", requestId },
+            };
+        }
+        return {
+            status: 400,
+            body: { error: "invalid_request", detail: "The request body is invalid.", requestId, issues },
+        };
+    }
+    if (Predicate.isTagged(error, "SignInCheckLimited")) {
+        const { retryAfterSeconds } = error;
+        return {
+            status: 429,
+            body: {
+                error: "rate_limited",
+                detail: "Too many sign-in checks. Wait a minute, then try again.",
+                requestId,
+            },
+            headers: { "retry-after": String(retryAfterSeconds) },
+        };
+    }
+    if (Predicate.isTagged(error, "InvalidQuery")) {
+        return {
+            status: 400,
+            body: {
+                error: "invalid_request",
+                detail: "The query is invalid.",
+                requestId,
+                issues: error.issues,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "InvalidActionInput")) {
+        return {
+            status: 422,
+            body: {
+                error: "invalid_input",
+                detail: "The action's input is invalid.",
+                requestId,
+                issues: error.issues,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "TriggerInputInvalid")) {
+        const { trigger, issues } = error;
+        return {
+            status: 422,
+            body: {
+                error: "trigger_input_invalid",
+                detail: `The input action trigger ${trigger} maps is not one its workflow accepts.`,
+                requestId,
+                trigger,
+                issues,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "WorkflowRecoveryUnavailable")) {
+        return {
+            status: 503,
+            body: {
+                error: "workflow_recovery_unavailable",
+                detail: "The action was not run: the recovery run that guarantees its workflow starts could " +
+                    "not be scheduled. Retry the same request.",
+                requestId,
+                retryable: true,
+            },
+            headers: { "retry-after": "5" },
+        };
+    }
+    if (Predicate.isTagged(error, "ActionRejected")) {
+        const message = String(error.message);
+        return {
+            status: 422,
+            body: {
+                error: "action_rejected",
+                detail: message,
+                requestId,
+                issues: [{ path: [], message }],
+                ...batchDetails(error),
+                ...limitDetails(error),
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "PermissionDenied")) {
+        const { permission, updating } = error;
+        if (updating === true) {
+            return {
+                status: 503,
+                body: {
+                    error: "ontology_updating",
+                    detail: "The app is being updated. Retry the same request shortly.",
+                    requestId,
+                    retryable: true,
+                },
+                headers: { "retry-after": "5" },
+            };
+        }
+        return {
+            status: 403,
+            body: {
+                error: "forbidden",
+                detail: typeof permission === "string"
+                    ? `${permission} is required.`
+                    : "Your permissions do not allow this.",
+                requestId,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "ScopeViolated")) {
+        const { entity, permission } = error;
+        return {
+            status: 403,
+            body: {
+                error: "forbidden",
+                detail: typeof permission === "string"
+                    ? `${permission} does not cover the record as the change would leave it.`
+                    : "Your permissions do not cover the record as the change would leave it.",
+                requestId,
+                ...(typeof entity === "string" ? { entity } : {}),
+                ...(typeof permission === "string" ? { permission } : {}),
+                ...batchDetails(error),
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "ScopedMetricQueryUnavailable")) {
+        const { entity, reason } = error;
+        return {
+            status: 403,
+            body: {
+                error: "scoped_aggregate_unavailable",
+                detail: `Your read of ${entity} is scoped, and this metric query cannot apply the scope; ` +
+                    `list ${entity} records instead.`,
+                requestId,
+                entity,
+                ...(reason === undefined ? {} : { reason }),
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "ReadDenied")) {
+        const { permissions } = error;
+        return {
+            status: 403,
+            body: {
+                error: "forbidden",
+                detail: `${listed(permissions)} ${permissions.length === 1 ? "is" : "are"} required.`,
+                requestId,
+                permissions,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "MetricQueryLimited")) {
+        const { retryAfterSeconds } = error;
+        return {
+            status: 429,
+            body: {
+                error: "rate_limited",
+                detail: `Too many metric queries. Wait ${retryAfterSeconds} seconds, then try again.`,
+                requestId,
+                retryable: true,
+            },
+            headers: { "retry-after": String(retryAfterSeconds) },
+        };
+    }
+    if (Predicate.isTagged(error, "InvalidMetricQuery")) {
+        return {
+            status: 400,
+            body: {
+                error: "invalid_aggregate_query",
+                detail: error.reason,
+                requestId,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "MetricQueriesUnavailable")) {
+        return {
+            status: 503,
+            body: {
+                error: "aggregate_unavailable",
+                detail: "Metric queries are available in production deployments.",
+                requestId,
+                retryable: false,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "WarehouseReadUnavailable")) {
+        const failure = error;
+        return failure.reason === "limited"
+            ? rateLimited(requestId, "Too many warehouse record reads.", failure.retryAfterSeconds ?? 60)
+            : {
+                status: 503,
+                body: {
+                    error: "warehouse_read_unavailable",
+                    detail: failure.reason === "not_configured"
+                        ? "Warehouse record reads require a production workspace credential."
+                        : "The warehouse could not complete this record read. Try again shortly.",
+                    requestId,
+                    retryable: failure.reason !== "not_configured",
+                },
+            };
+    }
+    if (Predicate.isTagged(error, "ConversationArchiveUnavailable")) {
+        return {
+            status: 502,
+            body: {
+                error: "conversation_archive_unavailable",
+                detail: "The conversation archive is unavailable. Try again shortly.",
+                requestId,
+                retryable: true,
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "MetricQueryUpstreamUnavailable")) {
+        const { reason } = error;
+        return {
+            status: 502,
+            body: {
+                error: "aggregate_upstream_unavailable",
+                detail: UPSTREAM_DETAILS[reason],
+                requestId,
+                retryable: reason === "unreachable" || reason === "timeout",
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "ConnectionError")) {
+        return connectionFailure(error, requestId);
+    }
+    if (Predicate.isTagged(error, "NotFound")) {
+        const { entity, id } = error;
+        return {
+            status: 404,
+            body: {
+                error: "not_found",
+                detail: "The record was not found.",
+                requestId,
+                ...(typeof entity === "string" ? { entity } : {}),
+                ...(typeof id === "string" ? { id } : {}),
+                ...batchDetails(error),
+            },
+        };
+    }
+    if (Predicate.isTagged(error, "Conflict")) {
+        const { entity, property, retryAfter } = error;
+        const wait = typeof retryAfter === "number" ? retryAfter : undefined;
+        return {
+            status: 409,
+            body: {
+                error: "conflict",
+                detail: wait === undefined
+                    ? "The change conflicts with existing records."
+                    : "Another attempt holds the record. Retry the same request after retry_after seconds.",
+                requestId,
+                ...(typeof entity === "string" ? { entity } : {}),
+                ...(typeof property === "string" ? { property } : {}),
+                ...(wait === undefined ? {} : { retryable: true, retry_after: wait }),
+                ...batchDetails(error),
+            },
+            ...(wait === undefined ? {} : { headers: { "retry-after": String(wait) } }),
+        };
+    }
+    return undefined;
+}
+/**
+ * Turns a failed request into a response. Expected failures map to their status; anything else is
+ * logged with the full cause and answered with a sanitized 500 that carries only the request id.
+ * Interruptions stay interruptions: the client is gone.
+ */
+export function failureResponse(cause, requestId) {
+    if (Cause.hasInterruptsOnly(cause)) {
+        return Effect.failCause(cause);
+    }
+    const typedFailure = Option.getOrUndefined(Cause.findErrorOption(cause));
+    const defect = typedFailure === undefined ? Cause.squash(cause) : undefined;
+    const error = typedFailure ?? (defect instanceof DeploymentAdmissionError ? defect : undefined);
+    const expected = error === undefined ? undefined : expectedFailure(error, requestId);
+    if (expected !== undefined) {
+        return Effect.succeed(toServerResponse(expected));
+    }
+    if (isStorageFailure(error)) {
+        return Effect.logError("ontology.storage.failed", cause).pipe(Effect.annotateLogs({ requestId }), Effect.as(toServerResponse(storageUnavailable(requestId))));
+    }
+    return Effect.logError("ontology.request.failed", cause).pipe(Effect.annotateLogs({ requestId }), Effect.as(toServerResponse(internalError(requestId))));
+}