@webda/grpc 4.0.0-beta.3

package/.webda/cache

@@ -0,0 +1,4 @@
+{
+  "sourceDigest": "ef8993a88f12bb10819b2de56248a24f",
+  "moduleDigest": "7e3441f5c16d35b42aeebaa1b3832f2b"
+}

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## [4.0.0-beta.3](https://github.com/loopingz/webda.io/compare/grpc-v4.0.0-beta.1...grpc-v4.0.0-beta.3) (2026-10-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* **compiler:** the accessors, loadParameters and unserializer modules are removed. They wrote into the sources what webdac build now generates through @webda/content-mapper, or methods nothing calls. The unused webdac build --code flag is removed too.
+* @webda/ts-plugin and the `tsc-esm` binary are removed, and applications now build with TypeScript 7.1. Generated code changes where TypeScript 6 was wrong, each verified against the shipped output:
+    - AuditEntry.timestamp, declared `number`, is no longer coerced to Date;
+    - AbstractOwnerModel no longer emits `new ModelLink(T)`, a ReferenceError
+      on first raw-uuid assignment;
+    - sample-app's `User extends WebdaUser` is now treated as a model (TS6's
+      base-chain guard was keyed on class name), so its relations are
+      initialised and coerced;
+    - imports use the specifier the author wrote, not monorepo-relative paths
+      that only resolve inside this repository;
+    - the emitted .d.ts is valid (TS6 referenced PrimaryKeyType unimported and
+      wrote BelongTo without its type argument).
+    A build that cannot write its module now fails; under TS6 a strict
+    file-naming violation was logged and the build still reported success.
+* **compiler:** model relations are now `type: "string"` in Input, Output and Stored schemas instead of an object with no properties, and six services gain the `type` property they inherit from ServiceParameters. Anything generated from these schemas — API validation, client types — changes with them.
+
+### Features
+
+* add build hooks ([97016bc](https://github.com/loopingz/webda.io/commit/97016bcb9a7becfa87793fa6cc408784487e7e07))
+* add grpc module and sample-app webui ([#756](https://github.com/loopingz/webda.io/issues/756)) ([4a7df9a](https://github.com/loopingz/webda.io/commit/4a7df9aacff8ca5e16c57e5fa9f2e2f0dc786e2f))
+* blog-system Binary/Binaries demo + e2e suite, with framework fixes ([#771](https://github.com/loopingz/webda.io/issues/771)) ([fe7e187](https://github.com/loopingz/webda.io/commit/fe7e18786744134fb29447a9f139689abbbd4950))
+* build on TypeScript 7.1; delete @webda/ts-plugin and ts-patch ([0008e97](https://github.com/loopingz/webda.io/commit/0008e97919524d44528a8e3e89ee27cfaa2ee93b))
+* **compiler:** generate schemas with @webda/content-mapper ([af3b7c5](https://github.com/loopingz/webda.io/commit/af3b7c5daa3ba239210be2af490850cde3460d84))
+* **content-mapper:** TypeScript 7.1 content mapper package ([9b57565](https://github.com/loopingz/webda.io/commit/9b57565a467d83671559fa4e2411124a5ae51109))
+* enhance debug panels ([#759](https://github.com/loopingz/webda.io/issues/759)) ([63e6e0c](https://github.com/loopingz/webda.io/commit/63e6e0c3bd7d72fb06b148c7344eb3021d186ae9))
+* WebdaQLString<T> branded type + ts-plugin compile-time validator ([#772](https://github.com/loopingz/webda.io/issues/772)) ([f0c14c1](https://github.com/loopingz/webda.io/commit/f0c14c1d5511b6f5e4f52633a23b3d2fe07b86c1))
+
+
+### Bug Fixes
+
+* compiler metadata, CLI commands, cron/async hooks and long-running command lifecycle ([#785](https://github.com/loopingz/webda.io/issues/785)) ([0515715](https://github.com/loopingz/webda.io/commit/05157157c9f52af3c8df720f6630053cd2dc8b98))
+* **compiler:** make webdac code a working migration tool ([578ca7b](https://github.com/loopingz/webda.io/commit/578ca7b5243701a4ba1d9a9685c38b2f89ac27ed))
+* unit test models relations ([2d160f1](https://github.com/loopingz/webda.io/commit/2d160f18d2139b362e8a12f935e15eaad27a808a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @webda/workout bumped to 4.0.0-beta.3
+  * devDependencies
+    * @webda/compiler bumped to 4.0.0-beta.3
+    * @webda/core bumped to 4.0.0-beta.3
+    * @webda/test bumped to 4.0.0-beta.3
+    * @webda/utils bumped to 4.0.0-beta.3
+  * peerDependencies
+    * @webda/core bumped from ^4.0.0-beta.1 to ^4.0.0-beta.3

package/LICENSE

@@ -0,0 +1,166 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
+

package/README.md

@@ -0,0 +1,100 @@
+# @webda/grpc module
+
+This module is part of Webda Application Framework that allows you to quickly develop applications with all modern prerequisites: Security, Extensibility, GraphQL, REST, CloudNative [https://webda.io](https://webda.io)
+
+<img src="https://webda.io/images/webda.svg" width="128" />
+
+![CI](https://github.com/loopingz/webda.io/workflows/CI/badge.svg)
+
+[![Join the chat at https://gitter.im/loopingz/webda](https://badges.gitter.im/loopingz/webda.svg)](https://gitter.im/loopingz/webda?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![codecov](https://codecov.io/gh/loopingz/webda.io/branch/main/graph/badge.svg?token=8N9DNM3K3O)](https://codecov.io/gh/loopingz/webda.io)
+[![SonarCloud.io](https://sonarcloud.io/api/project_badges/measure?project=loopingz_webda.io&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=loopingz_webda.io)
+![CodeQL](https://github.com/loopingz/webda.io/workflows/CodeQL/badge.svg)
+
+<!-- README_HEADER -->
+
+# @webda/grpc
+
+> gRPC transport for Webda — exposes registered operations as gRPC services over HTTP/2, with auto-generated `.proto` files from the operation registry.
+
+## When to use it
+
+- You want to expose Webda operations to gRPC clients (mobile apps, microservices, inter-service calls) alongside the existing REST API.
+- You are running the multi-protocol dev server (`webda debug`) and need gRPC on the same TLS port as REST and GraphQL.
+- You need a generated `.proto` file that stays in sync with your operation registry automatically on every `webdac build`.
+
+## Install
+
+```bash
+pnpm add @webda/grpc
+```
+
+## Configuration
+
+```json
+{
+  "services": {
+    "grpc": {
+      "type": "GrpcService",
+      "protoFile": ".webda/app.proto",
+      "packageName": "webda"
+    }
+  }
+}
+```
+
+| Parameter | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `protoFile` | string | `".webda/app.proto"` | No | Path where the generated `.proto` file is written and loaded from |
+| `packageName` | string | `"webda"` | No | Protobuf package name used in the generated `.proto` |
+
+## Usage
+
+```typescript
+// 1. Annotate operations in your model/service:
+import { Operation } from "@webda/core";
+
+export class PostService extends Service {
+  @Operation({ input: "CreatePostInput", output: "Post" })
+  async createPost(ctx: OperationContext<CreatePostInput>): Promise<Post> {
+    const body = await ctx.getInput();
+    return new Post(body).save();
+  }
+}
+
+// 2. Build to generate the .proto file:
+//    webdac build
+//    → writes .webda/app.proto
+
+// 3. Start the server (gRPC is multiplexed on the same port as REST):
+//    webda serve
+//    → gRPC requests with content-type: application/grpc are routed to GrpcService
+
+// 4. Call from a gRPC client (example using grpcurl):
+//    grpcurl -plaintext -d '{"title":"Hello"}' localhost:18080 webda.PostService/CreatePost
+```
+
+## Reference
+
+- API reference: see the auto-generated typedoc at `docs/pages/Modules/grpc/`.
+- Source: [`packages/grpc`](https://github.com/loopingz/webda.io/tree/main/packages/grpc)
+- Related: [`@webda/graphql`](../graphql) for the GraphQL transport; [`@webda/core`](../core) for the `OperationsTransport` base class and operation registration.
+
+<!-- README_FOOTER -->
+## Sponsors
+
+<!--
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor](mailto:sponsor@webda.io)
+-->
+
+Arize AI is a machine learning observability and model monitoring platform. It helps you visualize, monitor, and explain your machine learning models. [Learn more](https://arize.com)
+
+[<img src="https://arize.com/hubfs/arize/brand/arize-logomark-1.png" width="200">](https://arize.com)
+
+Loopingz is a software development company that provides consulting and development services. [Learn more](https://loopingz.com)
+
+[<img src="https://loopingz.com/images/logo.png" width="200">](https://loopingz.com)
+
+Tellae is an innovative consulting firm specialized in cities transportation issues. We provide our clients, both public and private, with solutions to support your strategic and operational decisions. [Learn more](https://tellae.fr)
+
+[<img src="https://tellae.fr/" width="200">](https://tellae.fr)

package/lib/grpc-stream.d.ts

@@ -0,0 +1,109 @@
+import type { Http2ServerRequest, Http2ServerResponse } from "node:http2";
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * Parsed gRPC method definition with serializer/deserializer functions.
+ */
+export interface GrpcMethodDef<Req = any, Res = any> {
+    requestSerialize: (msg: Req) => Buffer;
+    requestDeserialize: (buf: Buffer) => Req;
+    responseSerialize: (msg: Res) => Buffer;
+    responseDeserialize: (buf: Buffer) => Res;
+    requestStream: boolean;
+    responseStream: boolean;
+}
+/**
+ * gRPC bidirectional stream handler.
+ *
+ * Manages frame parsing (5-byte header: compressed flag + 4-byte big-endian length),
+ * message deserialization, and response framing for HTTP/2 gRPC streams.
+ *
+ * Supports all four gRPC patterns:
+ * - Unary (single request, single response)
+ * - Server streaming (single request, stream of responses)
+ * - Client streaming (stream of requests, single response)
+ * - Bidirectional streaming (stream of requests, stream of responses)
+ */
+export declare class GrpcStream<RequestType = any, ResponseType = any> {
+    /** Sentinel value indicating successful stream setup */
+    static OK: symbol;
+    private onMessageHandler;
+    private onEndHandler?;
+    private onCancelHandler?;
+    private chunk;
+    private messageLength;
+    private request;
+    private response;
+    private definition;
+    /**
+     * Create a new GrpcStream to handle a single gRPC request/response lifecycle.
+     * @param req - the incoming HTTP/2 request carrying the gRPC frames
+     * @param res - the HTTP/2 response used to write gRPC frames and trailers
+     * @param definition - protobuf method definition providing serialize/deserialize functions
+     */
+    constructor(req: IncomingMessage | Http2ServerRequest, res: ServerResponse | Http2ServerResponse, definition: GrpcMethodDef<RequestType, ResponseType>);
+    /**
+     * Register handler for incoming messages
+     * @param handler - callback invoked with each deserialized request message
+     * @returns this instance for chaining
+     */
+    onMessage(handler: (message: RequestType) => void | Promise<void>): this;
+    /**
+     * Register handler for stream end (client finished sending)
+     * @param handler - callback invoked when the client closes the send side of the stream
+     * @returns this instance for chaining
+     */
+    onEnd(handler: () => void): this;
+    /**
+     * Register handler for stream cancellation (client disconnected)
+     * @param handler - callback invoked when the underlying connection is closed by the client
+     * @returns this instance for chaining
+     */
+    onCancel(handler: () => void): this;
+    /**
+     * Send a response message with gRPC framing.
+     * @param message - the response message to serialize and send
+     * @returns void
+     */
+    send(message: ResponseType): void;
+    /**
+     * End the response with gRPC status trailers.
+     * @param status - gRPC status code (0 = OK)
+     * @param message - optional status message included in grpc-message trailer
+     * @returns void
+     */
+    end(status?: number, message?: string): void;
+    /**
+     * Send a single unary response and close the stream.
+     * @param message - the response message to serialize and send before closing
+     * @returns void
+     */
+    sendUnary(message: ResponseType): void;
+    /**
+     * Send an error response and close the stream.
+     * @param status - gRPC status code indicating the error type
+     * @param message - human-readable error message included in grpc-message trailer
+     * @returns void
+     */
+    sendError(status: number, message: string): void;
+}
+/** gRPC status codes */
+export declare const GrpcStatus: {
+    readonly OK: 0;
+    readonly CANCELLED: 1;
+    readonly UNKNOWN: 2;
+    readonly INVALID_ARGUMENT: 3;
+    readonly DEADLINE_EXCEEDED: 4;
+    readonly NOT_FOUND: 5;
+    readonly ALREADY_EXISTS: 6;
+    readonly PERMISSION_DENIED: 7;
+    readonly RESOURCE_EXHAUSTED: 8;
+    readonly FAILED_PRECONDITION: 9;
+    readonly ABORTED: 10;
+    readonly OUT_OF_RANGE: 11;
+    readonly UNIMPLEMENTED: 12;
+    readonly INTERNAL: 13;
+    readonly UNAVAILABLE: 14;
+    readonly DATA_LOSS: 15;
+    readonly UNAUTHENTICATED: 16;
+};
+//# sourceMappingURL=grpc-stream.d.ts.map

package/lib/grpc-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grpc-stream.d.ts","sourceRoot":"","sources":["../src/grpc-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,GAAG,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG;IACjD,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC;IACvC,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,GAAG,CAAC;IACzC,iBAAiB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC;IACxC,mBAAmB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,GAAG,CAAC;IAC1C,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU,CAAC,WAAW,GAAG,GAAG,EAAE,YAAY,GAAG,GAAG;IAC3D,wDAAwD;IACxD,MAAM,CAAC,EAAE,SAAgB;IAEzB,OAAO,CAAC,gBAAgB,CAAiD;IACzE,OAAO,CAAC,YAAY,CAAC,CAAa;IAClC,OAAO,CAAC,eAAe,CAAC,CAAa;IACrC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,UAAU,CAA2C;IAE7D;;;;;OAKG;IACH,YACE,GAAG,EAAE,eAAe,GAAG,kBAAkB,EACzC,GAAG,EAAE,cAAc,GAAG,mBAAmB,EACzC,UAAU,EAAE,aAAa,CAAC,WAAW,EAAE,YAAY,CAAC,EAyCrD;IAED;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAGvE;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAG/B;IAED;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAGlC;IAED;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAOhC;IAED;;;;;OAKG;IACH,GAAG,CAAC,MAAM,GAAE,MAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAO9C;IAED;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAGrC;IAED;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/C;CACF;AAED,wBAAwB;AACxB,eAAO,MAAM,UAAU;aACrB,EAAE,EAAE,CAAC;aACL,SAAS,EAAE,CAAC;aACZ,OAAO,EAAE,CAAC;aACV,gBAAgB,EAAE,CAAC;aACnB,iBAAiB,EAAE,CAAC;aACpB,SAAS,EAAE,CAAC;aACZ,cAAc,EAAE,CAAC;aACjB,iBAAiB,EAAE,CAAC;aACpB,kBAAkB,EAAE,CAAC;aACrB,mBAAmB,EAAE,CAAC;aACtB,OAAO,EAAE,EAAE;aACX,YAAY,EAAE,EAAE;aAChB,aAAa,EAAE,EAAE;aACjB,QAAQ,EAAE,EAAE;aACZ,WAAW,EAAE,EAAE;aACf,SAAS,EAAE,EAAE;aACb,eAAe,EAAE,EAAE;CACX,CAAC"}

package/lib/grpc-stream.js

@@ -0,0 +1,162 @@
+/**
+ * gRPC bidirectional stream handler.
+ *
+ * Manages frame parsing (5-byte header: compressed flag + 4-byte big-endian length),
+ * message deserialization, and response framing for HTTP/2 gRPC streams.
+ *
+ * Supports all four gRPC patterns:
+ * - Unary (single request, single response)
+ * - Server streaming (single request, stream of responses)
+ * - Client streaming (stream of requests, single response)
+ * - Bidirectional streaming (stream of requests, stream of responses)
+ */
+export class GrpcStream {
+    /** Sentinel value indicating successful stream setup */
+    static OK = Symbol("OK");
+    onMessageHandler;
+    onEndHandler;
+    onCancelHandler;
+    chunk = null;
+    messageLength = 0;
+    request;
+    response;
+    definition;
+    /**
+     * Create a new GrpcStream to handle a single gRPC request/response lifecycle.
+     * @param req - the incoming HTTP/2 request carrying the gRPC frames
+     * @param res - the HTTP/2 response used to write gRPC frames and trailers
+     * @param definition - protobuf method definition providing serialize/deserialize functions
+     */
+    constructor(req, res, definition) {
+        this.request = req;
+        this.response = res;
+        this.definition = definition;
+        // Set gRPC response headers
+        this.response.setHeader("Content-Type", "application/grpc");
+        this.response.setHeader("Grpc-Accept-Encoding", "identity");
+        this.response.setHeader("Grpc-Encoding", "identity");
+        // Parse incoming gRPC frames
+        req.on("data", (data) => {
+            if (this.chunk === null) {
+                this.messageLength = data.readUInt32BE(1);
+                this.chunk = data;
+            }
+            else {
+                this.chunk = Buffer.concat([this.chunk, data]);
+            }
+            // Check if we have a complete message
+            while (this.chunk && this.chunk.length >= 5 + this.messageLength) {
+                const message = this.chunk.subarray(5, 5 + this.messageLength);
+                const deserialized = this.definition.requestDeserialize(message);
+                this.onMessageHandler?.(deserialized);
+                // Advance to next frame
+                this.chunk = this.chunk.subarray(5 + this.messageLength);
+                if (this.chunk.length >= 5) {
+                    this.messageLength = this.chunk.readUInt32BE(1);
+                }
+                else if (this.chunk.length === 0) {
+                    this.chunk = null;
+                }
+            }
+        });
+        req.on("end", () => {
+            this.onEndHandler?.();
+        });
+        req.on("close", () => {
+            this.onCancelHandler?.();
+        });
+    }
+    /**
+     * Register handler for incoming messages
+     * @param handler - callback invoked with each deserialized request message
+     * @returns this instance for chaining
+     */
+    onMessage(handler) {
+        this.onMessageHandler = handler;
+        return this;
+    }
+    /**
+     * Register handler for stream end (client finished sending)
+     * @param handler - callback invoked when the client closes the send side of the stream
+     * @returns this instance for chaining
+     */
+    onEnd(handler) {
+        this.onEndHandler = handler;
+        return this;
+    }
+    /**
+     * Register handler for stream cancellation (client disconnected)
+     * @param handler - callback invoked when the underlying connection is closed by the client
+     * @returns this instance for chaining
+     */
+    onCancel(handler) {
+        this.onCancelHandler = handler;
+        return this;
+    }
+    /**
+     * Send a response message with gRPC framing.
+     * @param message - the response message to serialize and send
+     * @returns void
+     */
+    send(message) {
+        const responseBuffer = this.definition.responseSerialize(message);
+        const frame = Buffer.alloc(5 + responseBuffer.length);
+        frame.writeUInt8(0, 0); // Not compressed
+        frame.writeUInt32BE(responseBuffer.length, 1);
+        responseBuffer.copy(frame, 5);
+        this.response.write(frame);
+    }
+    /**
+     * End the response with gRPC status trailers.
+     * @param status - gRPC status code (0 = OK)
+     * @param message - optional status message included in grpc-message trailer
+     * @returns void
+     */
+    end(status = 0, message) {
+        const trailers = { "grpc-status": String(status) };
+        if (message) {
+            trailers["grpc-message"] = encodeURIComponent(message);
+        }
+        this.response.addTrailers?.(trailers);
+        this.response.end();
+    }
+    /**
+     * Send a single unary response and close the stream.
+     * @param message - the response message to serialize and send before closing
+     * @returns void
+     */
+    sendUnary(message) {
+        this.send(message);
+        this.end(0);
+    }
+    /**
+     * Send an error response and close the stream.
+     * @param status - gRPC status code indicating the error type
+     * @param message - human-readable error message included in grpc-message trailer
+     * @returns void
+     */
+    sendError(status, message) {
+        this.end(status, message);
+    }
+}
+/** gRPC status codes */
+export const GrpcStatus = {
+    OK: 0,
+    CANCELLED: 1,
+    UNKNOWN: 2,
+    INVALID_ARGUMENT: 3,
+    DEADLINE_EXCEEDED: 4,
+    NOT_FOUND: 5,
+    ALREADY_EXISTS: 6,
+    PERMISSION_DENIED: 7,
+    RESOURCE_EXHAUSTED: 8,
+    FAILED_PRECONDITION: 9,
+    ABORTED: 10,
+    OUT_OF_RANGE: 11,
+    UNIMPLEMENTED: 12,
+    INTERNAL: 13,
+    UNAVAILABLE: 14,
+    DATA_LOSS: 15,
+    UNAUTHENTICATED: 16
+};
+//# sourceMappingURL=grpc-stream.js.map

package/lib/grpc-stream.js.map

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