@spine-event-engine/server 2.0.0-snapshot.25 → 2.0.0-snapshot.26

package/dist/services/read-request-status.js

@@ -0,0 +1,151 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { create, toBinary } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { AnyPacker, ValidationException } from "@spine-event-engine/core";
+import { ErrorSchema, ValidationErrorSchema } from "@spine-event-engine/proto";
+import { QueryValidationError, SubscriptionValidationError, TopicValidationError, } from "@spine-event-engine/proto/client";
+/**
+ * Maps read-side validation to native Spine Error trailers and Connect details.
+ */
+export const ReadRequestStatus = {
+    /**
+     * Maps policy failures to sanitized transport codes without exposing private messages.
+     * @param error Policy, handler, or storage failure.
+     * @param message Public boundary failure message.
+     * @returns Sanitized recognized status or an internal error.
+     */
+    technical(error, message) {
+        const recognized = [
+            Code.Canceled,
+            Code.Unauthenticated,
+            Code.PermissionDenied,
+            Code.Unavailable,
+        ];
+        return new ConnectError(message, error instanceof ConnectError && recognized.includes(error.code) ? error.code : Code.Internal);
+    },
+    /**
+     * Creates a structured NotFound for a receiving context's missing membership.
+     *
+     * @param error Confirmed missing tenant from the target context.
+     * @returns Native and Connect status carrying the stable tenant type.
+     */
+    unknownTenant(error) {
+        const value = create(ErrorSchema, {
+            type: error.type,
+            code: Code.NotFound,
+            message: error.message,
+        });
+        const metadata = new Headers({
+            "spine-error-bin": Buffer.from(toBinary(ErrorSchema, value)).toString("base64"),
+        });
+        return new ConnectError(error.message, Code.NotFound, metadata, [{ desc: ErrorSchema, value }], error);
+    },
+    /**
+     * Creates the status for a well-formed activation without a registry record.
+     *
+     * @returns A structured NotFound status for direct and managed clients.
+     */
+    unknownSubscription() {
+        const message = "Subscription is unknown to this server.";
+        const value = create(ErrorSchema, {
+            type: "spine.client.SubscriptionValidationError",
+            code: SubscriptionValidationError.UNKNOWN_SUBSCRIPTION,
+            message,
+        });
+        const metadata = new Headers({
+            "spine-error-bin": Buffer.from(toBinary(ErrorSchema, value)).toString("base64"),
+        });
+        return new ConnectError(message, Code.NotFound, metadata, [{ desc: ErrorSchema, value }]);
+    },
+    /**
+     * Validates a complete request and sanitizes unexpected validator failures.
+     *
+     * @param kind The public request kind.
+     * @param validate Performs declared Protobuf validation.
+     */
+    check(kind, validate) {
+        try {
+            validate();
+        }
+        catch (error) {
+            if (error instanceof ValidationException) {
+                throw ReadRequestStatus.invalid(kind, false, `${kind} validation failed.`, AnyPacker.pack(ValidationErrorSchema, error.asMessage()));
+            }
+            throw new ConnectError("Read request validation failed.", Code.Internal);
+        }
+    },
+    /**
+     * Rejects unusable Topic criteria in lifecycle requests before record access.
+     *
+     * @param subscription Validated activation or cancellation request.
+     */
+    checkLifecycleCriterion(subscription) {
+        const criterion = subscription.topic?.target?.criterion;
+        if (criterion?.case === "includeAll" && criterion.value)
+            return;
+        if (criterion?.case === "filters") {
+            const filters = criterion.value;
+            if ((filters.idFilter?.id.length ?? 0) > 0 || filters.filter.length > 0)
+                return;
+            throw ReadRequestStatus.invalid("subscription", false, "Subscription requires an ID filter or field filter.");
+        }
+        throw ReadRequestStatus.invalid("subscription", false, "Subscription requires filters or include_all = true.");
+    },
+    /**
+     * Maps tenant admission to a distinct structured status.
+     *
+     * @param type Existing tenant failure type.
+     * @param message Safe tenant explanation.
+     * @returns A structured InvalidArgument status.
+     */
+    tenant(type, message) {
+        const value = create(ErrorSchema, { type, code: Code.InvalidArgument, message });
+        const metadata = new Headers({
+            "spine-error-bin": Buffer.from(toBinary(ErrorSchema, value)).toString("base64"),
+        });
+        return new ConnectError(message, Code.InvalidArgument, metadata, [
+            { desc: ErrorSchema, value },
+        ]);
+    },
+    /**
+     * Creates an InvalidArgument status with an enum-qualified Spine Error.
+     *
+     * @param kind The invalid read-side request.
+     * @param unsupported Whether its target is not registered.
+     * @param message Safe public explanation.
+     * @param details Declared constraint violations, when available.
+     * @returns A transport error carrying native and Connect structured details.
+     */
+    invalid(kind, unsupported, message, details) {
+        const type = `spine.client.${kind.charAt(0).toUpperCase()}${kind.slice(1)}ValidationError`;
+        const code = unsupported
+            ? kind === "query"
+                ? QueryValidationError.UNSUPPORTED_QUERY_TARGET
+                : TopicValidationError.UNSUPPORTED_TOPIC_TARGET
+            : kind === "query"
+                ? QueryValidationError.INVALID_QUERY
+                : kind === "topic"
+                    ? TopicValidationError.INVALID_TOPIC
+                    : SubscriptionValidationError.INVALID_SUBSCRIPTION;
+        const value = create(ErrorSchema, { type, code, message, details });
+        const metadata = new Headers({
+            "spine-error-bin": Buffer.from(toBinary(ErrorSchema, value)).toString("base64"),
+        });
+        return new ConnectError(message, Code.InvalidArgument, metadata, [
+            { desc: ErrorSchema, value },
+        ]);
+    },
+};
+//# sourceMappingURL=read-request-status.js.map

package/dist/services/read-request-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-request-status.js","sourceRoot":"","sources":["../../src/services/read-request-status.ts"],"names":[],"mappings":"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"}

package/dist/services/spine-services.d.ts

@@ -1,7 +1,28 @@
 import type { ILogLayer } from "loglayer";
-import { type ConnectRouter } from "@connectrpc/connect";
+import { type ConnectRouter, type HandlerContext } from "@connectrpc/connect";
+import type { ReaderProofVerifier } from "@spine-event-engine/core/spi/reader-forwarding";
 import { BoundedContext } from "../context/bounded-context.js";
+import { AppQueryExecution } from "./app-query-execution.js";
+import { type DirectReaderAuthenticator } from "./trusted-reader-ingress.js";
+import { ReadSideFilterEngine } from "../stand/read-side-filter-engine.js";
+/**
+ * Framework-only hooks for installing service read policies and App Query routing.
+ */
 interface SpineServicesAccess {
+    /**
+     * Attaches one Server's gRPC read policy before accepting requests.
+     *
+     * @param services Prepared service adapter.
+     * @param filters Registered policy engine.
+     */
+    installReadFilters(services: SpineServices, filters: ReadSideFilterEngine): void;
+    /**
+     * Attaches the Server-selected App Query capability before listener binding.
+     *
+     * @param services Adapter created for this Server.
+     * @param queries Exact-class handler table prepared by the Server.
+     */
+    installAppQueries(services: SpineServices, queries: AppQueryExecution): void;
     /**
      * Sets the server logger for service diagnostics.
      *
@@ -32,7 +53,8 @@ interface SpineServicesAccess {
  * Queries allow at most 100 IDs, 16 simple filters, 8 composites, and 8 orderings.
  * Use proto column names such as `open_task_count`, not generated TS local names
  * such as `openTaskCount`. Invalid columns, values, operators, and query shapes
- * return stable `INVALID_QUERY` responses before Stand storage is read.
+ * reject with structured `INVALID_ARGUMENT` and `INVALID_QUERY` details before
+ * Stand storage is read.
  *
  * `SubscriptionService.Subscribe` accepts known state targets with
  * `include_all` or validated ID/field filters and known event targets exposed
@@ -48,7 +70,9 @@ interface SpineServicesAccess {
  * rejected-command payload forms and stack trace from their client-facing
  * context.
  * Application code remains on generated domain event messages through handler
- * dispatch. Unknown or duplicate activation IDs complete without updates.
+ * dispatch. Unknown or expired activation IDs fail with `NOT_FOUND` and
+ * `UNKNOWN_SUBSCRIPTION` details. A duplicate active activation completes
+ * without another update stream.
  * Cancellation of unknown or already-cleaned IDs returns OK after admission to
  * the bounded unknown-removal pool.
  */
@@ -83,11 +107,16 @@ export interface SpineServicesOptions {
      */
     readonly contexts: readonly BoundedContext[];
     /**
-     * Maximum queued updates per active subscription before delivery is closed.
-     *
-     * Defaults to 100. Non-positive or non-finite values are coerced to 1.
+     * Existing native request-size bound used for internal reader assertions.
+     */
+    readonly readMaxBytes?: number;
+    /**
+     * Configured direct and trusted-peer authentication ports.
      */
-    readonly queueLimit?: number;
+    readonly readerAdmission?: Readonly<{
+        forwarded?: ReaderProofVerifier<HandlerContext>;
+        direct?: DirectReaderAuthenticator<HandlerContext>;
+    }>;
     /**
      * Maximum concurrent unknown-ID cancellation operations for this
      * `SpineServices` instance.

package/dist/services/spine-services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spine-services.d.ts","sourceRoot":"","sources":["../../src/services/spine-services.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAyE7E,OAAO,EAAE,cAAc,EAAwB,MAAM,+BAA+B,CAAC;AAerF,UAAU,mBAAmB;IAC3B;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAEhE;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,aAAa;;IAqBxB;;;;OAIG;gBACS,OAAO,EAAE,oBAAoB;IA4DzC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;CAqhB/C;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,mBAyBhC,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAGnC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAE7C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC"}
+{"version":3,"file":"spine-services.d.ts","sourceRoot":"","sources":["../../src/services/spine-services.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,EAAsB,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAUlG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gDAAgD,CAAC;AAgF1F,OAAO,EAAE,cAAc,EAAwB,MAAM,+BAA+B,CAAC;AAOrF,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,EAAwB,KAAK,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AASnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAY3E;;GAEG;AACH,UAAU,mBAAmB;IAC3B;;;;;OAKG;IACH,kBAAkB,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAEjF;;;;;OAKG;IACH,iBAAiB,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE7E;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAEhE;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,aAAa;;IAyBxB;;;;OAIG;gBACS,OAAO,EAAE,oBAAoB;IA4DzC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;CAg9B/C;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,mBA+ChC,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAGnC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC;QAClC,SAAS,CAAC,EAAE,mBAAmB,CAAC,cAAc,CAAC,CAAC;QAChD,MAAM,CAAC,EAAE,yBAAyB,CAAC,cAAc,CAAC,CAAC;KACpD,CAAC,CAAC;IAEH;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC"}