@ldtr/nestjs-webtransport 0.0.3 → 0.0.5

package/README.md

@@ -10,7 +10,7 @@ npm install @ldtr/nestjs-webtransport
 Usage
 =====
 
-Declare a server and a gateway:
+First, declare a server:
 ```ts
 import {
     WtSession,
@@ -40,7 +40,10 @@ export class MainWebTransportServer implements WebTransportServerOptionsFactory
         }
     }
 }
+```
 
+then, declare a gateway:
+```ts
 @WebTransportGateway({ server: "main", path: "/events" })
 export class EventsGateway implements WebTransportGatewayLifecycle {
     async onSession(session: WtSession): Promise<void> {
@@ -109,4 +112,46 @@ import { Module } from "@nestjs/common"
 })
 export class AppModule {
 }
-```
+```
+
+Session and stream data
+=======================
+
+Gateways are singleton providers in NestJS. Do not store session-specific or stream-specific state in gateway class properties. Instead, use the `data` object available on sessions and streams.
+
+You can type this data by passing a generic type to `WebTransportGatewayLifecycle`:
+
+```ts
+import {
+    WtSession,
+    WtStreamRW,
+    type GatewayData,
+    type WebTransportGatewayLifecycle
+} from "@ldtr/nestjs-webtransport"
+
+type EventsGatewayData = {
+    session: {
+        connectedAt: Date
+        totalBytes: number 
+    }
+    streamRW: {
+        receivedBytes: number 
+    }
+}
+
+@WebTransportGateway({ server: "main", path: "/events" })
+export class EventsGateway implements WebTransportGatewayLifecycle<EventsGatewayData> {
+    async onSession(session: WtSession<EventsGatewayData>): Promise<void> {
+        session.data.connectedAt = new Date()
+        session.data.totalBytes = 0
+    }
+
+    async onStreamRW(stream: WtStreamRW<EventsGatewayData>): Promise<void> {
+        stream.data.receivedBytes = 0
+
+        for await (const chunk of stream.read()) {
+            stream.data.receivedBytes += chunk.length
+            stream.session.data.totalBytes += chunk.length
+        }
+    }
+}

package/dist/index.cjs

@@ -50,6 +50,10 @@ async function* generateUStream(session) {
 		reader.releaseLock();
 	}
 }
+function isSessionClosedNormally(error) {
+	if (!(error instanceof Error)) return false;
+	return error.name === "WebTransportError" && /session closed/i.test(error.message) && /code 0/i.test(error.message);
+}
 async function* generateChunks(reader) {
 	try {
 		while (true) {
@@ -57,6 +61,8 @@ async function* generateChunks(reader) {
 			if (done) break;
 			yield value;
 		}
+	} catch (error) {
+		if (!isSessionClosedNormally(error)) throw error;
 	} finally {
 		reader.releaseLock();
 	}
@@ -114,6 +120,7 @@ var WritableStreamHandler = class extends AbstractStreamHandler {
 var AbstractWtStream = class {
 	session;
 	webTransportStream;
+	data;
 	constructor(session, webTransportStream) {
 		this.session = session;
 		this.webTransportStream = webTransportStream;
@@ -233,6 +240,41 @@ let WebTransportServerExplorer = class WebTransportServerExplorer {
 };
 WebTransportServerExplorer = __decorate([(0, _nestjs_common.Injectable)(), __decorateMetadata("design:paramtypes", [typeof _nestjs_core.DiscoveryService === "undefined" ? Object : _nestjs_core.DiscoveryService])], WebTransportServerExplorer);
 //#endregion
+//#region src/lib/bootstraps/web-transport-bootstrapper.ts
+var _WebTransportBootstrapper;
+let WebTransportBootstrapper = _WebTransportBootstrapper = class WebTransportBootstrapper {
+	serverFactory;
+	webTransportExplorer;
+	logger = new _nestjs_common.Logger(_WebTransportBootstrapper.name);
+	h3ServersWithInfo = [];
+	constructor(serverFactory, webTransportExplorer) {
+		this.serverFactory = serverFactory;
+		this.webTransportExplorer = webTransportExplorer;
+	}
+	async onApplicationBootstrap() {
+		const serverBindings = this.webTransportExplorer.discover();
+		this.h3ServersWithInfo = await this.serverFactory.createH3Servers(serverBindings);
+		await Promise.all(this.h3ServersWithInfo.map(async ({ options, name, h3Server }) => {
+			try {
+				h3Server.startServer();
+				await h3Server.ready;
+				this.logger.log(`WebTransport server "${name}" is ready on ${options.host}:${options.port}`);
+			} catch (e) {
+				this.logger.error(`Failed to start WebTransport server "${name}" on ${options.host}:${options.port}`);
+				throw e;
+			}
+		}));
+	}
+	async onApplicationShutdown() {
+		await Promise.all(this.h3ServersWithInfo.map(async ({ name, h3Server }) => {
+			h3Server.stopServer();
+			await h3Server.closed;
+			this.logger.log(`WebTransport server "${name}" stopped`);
+		}));
+	}
+};
+WebTransportBootstrapper = _WebTransportBootstrapper = __decorate([(0, _nestjs_common.Injectable)(), __decorateMetadata("design:paramtypes", [Object, Object])], WebTransportBootstrapper);
+//#endregion
 //#region src/lib/explorers/web-transport.explorer.ts
 var _WebTransportExplorer;
 let WebTransportExplorer = _WebTransportExplorer = class WebTransportExplorer {
@@ -259,7 +301,7 @@ let WebTransportExplorer = _WebTransportExplorer = class WebTransportExplorer {
 		return serverBindings;
 	}
 };
-WebTransportExplorer = _WebTransportExplorer = __decorate([(0, _nestjs_common.Injectable)(), __decorateMetadata("design:paramtypes", [typeof WebTransportServerExplorer === "undefined" ? Object : WebTransportServerExplorer, typeof WebTransportGatewayExplorer === "undefined" ? Object : WebTransportGatewayExplorer])], WebTransportExplorer);
+WebTransportExplorer = _WebTransportExplorer = __decorate([(0, _nestjs_common.Injectable)(), __decorateMetadata("design:paramtypes", [Object, Object])], WebTransportExplorer);
 //#endregion
 //#region src/lib/bootstraps/consumers/abstract-stream.consumer.ts
 var AbstractStreamConsumer = class {
@@ -307,6 +349,7 @@ StreamRWConsumer = _StreamRWConsumer = __decorate([(0, _nestjs_common.Injectable
 //#region src/lib/classes/wt-session.ts
 var WtSession = class {
 	webTransportSession;
+	data;
 	constructor(webTransportSession) {
 		this.webTransportSession = webTransportSession;
 	}
@@ -395,42 +438,7 @@ let ServerFactory = _ServerFactory = class ServerFactory {
 		this.streamROConsumer.consume(gateway, webTransportSession, session).catch((error) => this.logger.error(error));
 	}
 };
-ServerFactory = _ServerFactory = __decorate([(0, _nestjs_common.Injectable)(), __decorateMetadata("design:paramtypes", [typeof StreamRWConsumer === "undefined" ? Object : StreamRWConsumer, typeof StreamROConsumer === "undefined" ? Object : StreamROConsumer])], ServerFactory);
-//#endregion
-//#region src/lib/bootstraps/web-transport-bootstrapper.ts
-var _WebTransportBootstrapper;
-let WebTransportBootstrapper = _WebTransportBootstrapper = class WebTransportBootstrapper {
-	serverFactory;
-	webTransportExplorer;
-	logger = new _nestjs_common.Logger(_WebTransportBootstrapper.name);
-	h3ServersWithInfo = [];
-	constructor(serverFactory, webTransportExplorer) {
-		this.serverFactory = serverFactory;
-		this.webTransportExplorer = webTransportExplorer;
-	}
-	async onApplicationBootstrap() {
-		const serverBindings = this.webTransportExplorer.discover();
-		this.h3ServersWithInfo = await this.serverFactory.createH3Servers(serverBindings);
-		await Promise.all(this.h3ServersWithInfo.map(async ({ options, name, h3Server }) => {
-			try {
-				h3Server.startServer();
-				await h3Server.ready;
-				this.logger.log(`WebTransport server "${name}" is ready on ${options.host}:${options.port}`);
-			} catch (e) {
-				this.logger.error(`Failed to start WebTransport server "${name}" on ${options.host}:${options.port}`);
-				throw e;
-			}
-		}));
-	}
-	async onApplicationShutdown() {
-		await Promise.all(this.h3ServersWithInfo.map(async ({ name, h3Server }) => {
-			h3Server.stopServer();
-			await h3Server.closed;
-			this.logger.log(`WebTransport server "${name}" stopped`);
-		}));
-	}
-};
-WebTransportBootstrapper = _WebTransportBootstrapper = __decorate([(0, _nestjs_common.Injectable)(), __decorateMetadata("design:paramtypes", [typeof ServerFactory === "undefined" ? Object : ServerFactory, typeof WebTransportExplorer === "undefined" ? Object : WebTransportExplorer])], WebTransportBootstrapper);
+ServerFactory = _ServerFactory = __decorate([(0, _nestjs_common.Injectable)(), __decorateMetadata("design:paramtypes", [Object, Object])], ServerFactory);
 //#endregion
 //#region src/lib/webtransport.module.ts
 let WebTransportModule = class WebTransportModule {};

package/dist/index.d.cts

@@ -12,23 +12,20 @@ interface WebTransportServerOptions {
 }
 declare function WebTransportServer(options: WebTransportServerOptions): ClassDecorator;
 //#endregion
-//#region src/lib/explorers/webtransport-server.explorer.d.ts
-type WebTransportServerOptionsFactory = {
-  options(): HttpServerInit$1 | Promise<HttpServerInit$1>;
-};
-//#endregion
 //#region src/lib/classes/wt-session.d.ts
-declare class WtSession {
+declare class WtSession<GD extends GatewayData = GatewayDefaultData> {
   private readonly webTransportSession;
+  data?: GD["session"];
   constructor(webTransportSession: WebTransportSession);
-  createStreamWO(): Promise<WtStreamWO>;
-  createStreamRW(): Promise<WtStreamRW>;
+  createStreamWO(): Promise<WtStreamWO<GD>>;
+  createStreamRW(): Promise<WtStreamRW<GD>>;
 }
 //#endregion
 //#region src/lib/classes/wt-stream.d.ts
-declare abstract class AbstractWtStream<TWebStream> {
+declare abstract class AbstractWtStream<TWebStream, Data extends object | undefined> {
   readonly session: WtSession;
   protected readonly webTransportStream: TWebStream;
+  data?: Data;
   protected constructor(session: WtSession, webTransportStream: TWebStream);
 }
 interface WtReadableStream {
@@ -39,7 +36,7 @@ interface WtWritableStream {
   write(data: Uint8Array): Promise<void>;
   closeWritable(): Promise<void>;
 }
-declare class WtStreamRW extends AbstractWtStream<WebTransportBidirectionalStream> implements WtReadableStream, WtWritableStream {
+declare class WtStreamRW<GD extends GatewayData = GatewayDefaultData> extends AbstractWtStream<WebTransportBidirectionalStream, GD["streamRW"]> implements WtReadableStream, WtWritableStream {
   private readonly readableStreamHandler;
   private readonly writableStreamHandler;
   constructor(session: WtSession, webTransportStream: WebTransportBidirectionalStream);
@@ -49,19 +46,24 @@ declare class WtStreamRW extends AbstractWtStream<WebTransportBidirectionalStrea
   closeWritable(): Promise<void>;
   close(): Promise<void>;
 }
-declare class WtStreamRO extends AbstractWtStream<WebTransportReceiveStream> implements WtReadableStream {
+declare class WtStreamRO<GD extends GatewayData = GatewayDefaultData> extends AbstractWtStream<WebTransportReceiveStream, GD["streamRO"]> implements WtReadableStream {
   private readonly readableStreamHandler;
   constructor(session: WtSession, webTransportStream: WebTransportReceiveStream);
   read(): AsyncIterableIterator<Uint8Array>;
   closeReadable(): Promise<void>;
 }
-declare class WtStreamWO extends AbstractWtStream<WebTransportSendStream> implements WtWritableStream {
+declare class WtStreamWO<GD extends GatewayData = GatewayDefaultData> extends AbstractWtStream<WebTransportSendStream, GD["streamWO"]> implements WtWritableStream {
   private readonly writableStreamHandler;
   constructor(session: WtSession, webTransportStream: WebTransportSendStream);
   write(data: Uint8Array): Promise<void>;
   closeWritable(): Promise<void>;
 }
 //#endregion
+//#region src/lib/explorers/webtransport-server.explorer.d.ts
+type WebTransportServerOptionsFactory = {
+  options(): HttpServerInit$1 | Promise<HttpServerInit$1>;
+};
+//#endregion
 //#region src/lib/bootstraps/types.d.ts
 type WebTransportRequestHeader = {
   readonly ':path': string;
@@ -70,16 +72,28 @@ type WebTransportRequest = {
   readonly header: WebTransportRequestHeader;
 };
 //#endregion
-//#region src/lib/explorers/webtransport-gateway.explorer.d.ts
-type WebTransportGatewayLifecycle = {
+//#region src/lib/types/web-transport-gateway-lifecycle.d.ts
+type GatewayData = {
+  session?: object;
+  streamRW?: object;
+  streamWO?: object;
+  streamRO?: object;
+};
+type GatewayDefaultData = {
+  session: undefined;
+  streamRW: undefined;
+  streamWO: undefined;
+  streamRO: undefined;
+};
+type WebTransportGatewayLifecycle<GD extends GatewayData = GatewayDefaultData> = {
   allowRequest?(request: WebTransportRequest): void | Promise<void>;
-  onSession?(session: WtSession): void | Promise<void>;
-  onSessionClosed?(session: WtSession): void | Promise<void>;
-  onStreamRW?(stream: WtStreamRW): void | Promise<void>;
-  onStreamRO?(stream: WtStreamRO): void | Promise<void>;
+  onSession?(session: WtSession<GD>): void | Promise<void>;
+  onSessionClosed?(session: WtSession<GD>): void | Promise<void>;
+  onStreamRW?(stream: WtStreamRW<GD>): void | Promise<void>;
+  onStreamRO?(stream: WtStreamRO<GD>): void | Promise<void>;
 };
 //#endregion
 //#region src/lib/webtransport.module.d.ts
 declare class WebTransportModule {}
 //#endregion
-export { type HttpServerInit, WebTransportGateway, type WebTransportGatewayLifecycle, type WebTransportGatewayOptions, WebTransportModule, WebTransportServer, type WebTransportServerOptions, type WebTransportServerOptionsFactory, WtSession, WtStreamRO, WtStreamRW, WtStreamWO };
+export { type GatewayData, type HttpServerInit, WebTransportGateway, type WebTransportGatewayLifecycle, type WebTransportGatewayOptions, WebTransportModule, WebTransportServer, type WebTransportServerOptions, type WebTransportServerOptionsFactory, WtSession, WtStreamRO, WtStreamRW, WtStreamWO };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ldtr/nestjs-webtransport",
-    "version": "0.0.3",
+    "version": "0.0.5",
     "description": "NestJS module for creating WebTransport servers and gateways.",
     "type": "module",
     "files": [