@roj-ai/transport 0.1.36 → 0.2.2

package/src/core/connection.ts

@@ -92,12 +92,31 @@ export abstract class Connection<TReceive extends ProtocolDef, TSend extends Pro
 
 	private sendBuffer: string[] = []
 	private readonly maxBufferSize: number = 500
+	private droppedSinceLastFlush = 0
+
+	/**
+	 * Buffer one message, dropping the OLDEST on overflow.
+	 *
+	 * These are ephemeral notifications, so a stale one is worth less than a
+	 * fresh one — the previous behaviour dropped the newest and kept a queue of
+	 * 500 obsolete updates. Overflow is logged once per episode rather than per
+	 * message: silently vanishing notifications leave a "the UI stopped
+	 * updating" report with no server-side trace at all.
+	 */
+	private buffer(data: string): void {
+		if (this.sendBuffer.length >= this.maxBufferSize) {
+			this.sendBuffer.shift()
+			if (this.droppedSinceLastFlush === 0) {
+				console.warn(`[transport] send buffer full (${this.maxBufferSize}), dropping oldest notifications`)
+			}
+			this.droppedSinceLastFlush++
+		}
+		this.sendBuffer.push(data)
+	}
 
 	send(data: string): boolean {
 		if (!this.ws || this.ws.readyState !== WebSocketReadyState.OPEN) {
-			if (this.sendBuffer.length < this.maxBufferSize) {
-				this.sendBuffer.push(data)
-			}
+			this.buffer(data)
 			return false
 		}
 		this.flushSendBuffer()
@@ -105,9 +124,7 @@ export abstract class Connection<TReceive extends ProtocolDef, TSend extends Pro
 			this.ws.send(data)
 			return true
 		} catch {
-			if (this.sendBuffer.length < this.maxBufferSize) {
-				this.sendBuffer.push(data)
-			}
+			this.buffer(data)
 			return false
 		}
 	}
@@ -123,6 +140,10 @@ export abstract class Connection<TReceive extends ProtocolDef, TSend extends Pro
 				break
 			}
 		}
+		if (this.sendBuffer.length === 0 && this.droppedSinceLastFlush > 0) {
+			console.warn(`[transport] send buffer drained; ${this.droppedSinceLastFlush} notification(s) were dropped`)
+			this.droppedSinceLastFlush = 0
+		}
 	}
 
 	clearSendBuffer(): void {

package/src/core/index.ts

@@ -14,33 +14,19 @@ export type { Result } from './result.js'
 export { Err, flatMapResult, isErr, isOk, mapResult, Ok, unwrapOr, unwrapOrThrow } from './result.js'
 
 // Protocol Definition
-export { defineProtocol, method, notification } from './protocol.js'
+export { defineProtocol, notification } from './protocol.js'
 export type {
-	CallerFor,
-	EndpointDef,
-	EndpointHandler,
-	ExtractProtocolDef,
 	HandlerContext,
-	HandlersFor,
-	InferError,
 	InferInput,
-	InferOutput,
-	IsMethod,
-	IsNotification,
-	MethodCaller,
-	MethodDef,
-	MethodHandler,
-	MethodOptions,
 	NotificationDef,
 	NotificationHandler,
 	NotificationNotifier,
 	NotificationOptions,
-	NotifierFor,
 	Protocol,
-	ProtocolCaller,
 	ProtocolDef,
 	ProtocolHandlers,
 	ProtocolNotifier,
+	SafeParseResult,
 } from './protocol.js'
 
 // Message Router

package/src/core/protocol.ts

@@ -1,31 +1,16 @@
 /**
  * Protocol Definition API
  *
- * Provides a type-safe way to define RPC-like protocols for WebSocket communication.
- * Inspired by tRPC but designed for bidirectional WebSocket protocols.
+ * Type-safe definition of the notification protocols carried over the WebSocket
+ * link. Fire-and-forget only — request/response lives on HTTP `/rpc`.
  */
 
 import { z } from 'zod'
-import type { Result } from './result.js'
 
 // ============================================================================
-// Method/Notification Definition Types
+// Notification Definition Types
 // ============================================================================
 
-/**
- * Definition for a request-response method.
- */
-export interface MethodDef<
-	TInput extends z.ZodTypeAny = z.ZodTypeAny,
-	TOutput extends z.ZodTypeAny = z.ZodTypeAny,
-	TError extends z.ZodTypeAny = z.ZodTypeAny,
-> {
-	_type: 'method'
-	input: TInput
-	output: TOutput
-	error: TError
-}
-
 /**
  * Definition for a fire-and-forget notification.
  */
@@ -35,15 +20,10 @@ export interface NotificationDef<TInput extends z.ZodTypeAny = z.ZodTypeAny> {
 }
 
 /**
- * A single endpoint definition (method or notification).
- */
-export type EndpointDef = MethodDef | NotificationDef
-
-/**
- * Protocol definition - a collection of named endpoints.
+ * Protocol definition - a collection of named notifications.
  */
 export interface ProtocolDef {
-	[key: string]: EndpointDef
+	[key: string]: NotificationDef
 }
 
 // ============================================================================
@@ -51,40 +31,16 @@ export interface ProtocolDef {
 // ============================================================================
 
 /**
- * Extract input type from an endpoint definition.
- */
-export type InferInput<T extends EndpointDef> = T extends MethodDef<infer I, infer _O, infer _E> ? z.infer<I>
-	: T extends NotificationDef<infer I> ? z.infer<I>
-	: never
-
-/**
- * Extract output type from a method definition.
+ * Extract input type from a notification definition.
  */
-export type InferOutput<T extends MethodDef> = T extends MethodDef<infer _I, infer O, infer _E> ? z.infer<O>
-	: never
-
-/**
- * Extract error type from a method definition.
- */
-export type InferError<T extends MethodDef> = T extends MethodDef<infer _I, infer _O, infer E> ? z.infer<E>
-	: never
-
-/**
- * Check if endpoint is a method.
- */
-export type IsMethod<T extends EndpointDef> = T extends MethodDef ? true : false
-
-/**
- * Check if endpoint is a notification.
- */
-export type IsNotification<T extends EndpointDef> = T extends NotificationDef ? true : false
+export type InferInput<T extends NotificationDef> = z.infer<T['input']>
 
 // ============================================================================
 // Handler Types
 // ============================================================================
 
 /**
- * Handler context passed to method/notification handlers.
+ * Handler context passed to notification handlers.
  */
 export interface HandlerContext {
 	/** Connection identifier */
@@ -93,14 +49,6 @@ export interface HandlerContext {
 	[key: string]: unknown
 }
 
-/**
- * Handler for a method endpoint.
- */
-export type MethodHandler<T extends MethodDef> = (
-	input: InferInput<T>,
-	ctx: HandlerContext,
-) => Promise<Result<InferOutput<T>, InferError<T>>>
-
 /**
  * Handler for a notification endpoint.
  */
@@ -109,31 +57,17 @@ export type NotificationHandler<T extends NotificationDef> = (
 	ctx: HandlerContext,
 ) => Promise<void>
 
-/**
- * Handler for an endpoint (method or notification).
- */
-export type EndpointHandler<T extends EndpointDef> = T extends MethodDef ? MethodHandler<T>
-	: T extends NotificationDef ? NotificationHandler<T>
-	: never
-
 /**
  * Handlers object for a protocol.
  */
 export type ProtocolHandlers<T extends ProtocolDef> = {
-	[K in keyof T]: EndpointHandler<T[K]>
+	[K in keyof T]: NotificationHandler<T[K]>
 }
 
 // ============================================================================
-// Caller Types (for making outbound calls)
+// Notifier Types (for making outbound calls)
 // ============================================================================
 
-/**
- * Caller function for a method endpoint.
- */
-export type MethodCaller<T extends MethodDef> = (
-	input: InferInput<T>,
-) => Promise<Result<InferOutput<T>, InferError<T>>>
-
 /**
  * Notifier function for a notification endpoint.
  */
@@ -142,59 +76,16 @@ export type NotificationNotifier<T extends NotificationDef> = (
 ) => void
 
 /**
- * Caller object for methods in a protocol.
- * Only includes method endpoints.
- */
-export type ProtocolCaller<T extends ProtocolDef> = {
-	[K in keyof T as T[K] extends MethodDef ? K : never]: T[K] extends MethodDef ? MethodCaller<T[K]>
-		: never
-}
-
-/**
- * Notifier object for notifications in a protocol.
- * Only includes notification endpoints.
+ * Notifier object for the notifications in a protocol.
  */
 export type ProtocolNotifier<T extends ProtocolDef> = {
-	[K in keyof T as T[K] extends NotificationDef ? K : never]: T[K] extends NotificationDef ? NotificationNotifier<T[K]>
-		: never
+	[K in keyof T]: NotificationNotifier<T[K]>
 }
 
 // ============================================================================
 // Definition Functions
 // ============================================================================
 
-/**
- * Options for method definition.
- */
-export interface MethodOptions<
-	TInput extends z.ZodTypeAny,
-	TOutput extends z.ZodTypeAny,
-	TError extends z.ZodTypeAny,
-> {
-	/** Input schema (what the caller sends) */
-	input: TInput
-	/** Output schema (what the handler returns on success) */
-	output: TOutput
-	/** Error schema (what the handler returns on failure) */
-	error: TError
-}
-
-/**
- * Define a request-response method endpoint.
- */
-export function method<
-	TInput extends z.ZodTypeAny,
-	TOutput extends z.ZodTypeAny,
-	TError extends z.ZodTypeAny,
->(options: MethodOptions<TInput, TOutput, TError>): MethodDef<TInput, TOutput, TError> {
-	return {
-		_type: 'method',
-		input: options.input,
-		output: options.output,
-		error: options.error,
-	}
-}
-
 /**
  * Options for notification definition.
  */
@@ -226,47 +117,32 @@ export type SafeParseResult<T> =
 	| { success: true; data: T }
 	| { success: false; error: { message: string } }
 
+/** Parse through a generic schema type so the result keeps the schema's output type. */
+function safeParseWith<S extends z.ZodTypeAny>(schema: S, input: unknown): SafeParseResult<z.infer<S>> {
+	const result = schema.safeParse(input)
+	if (result.success) {
+		return { success: true, data: result.data }
+	}
+	return { success: false, error: { message: result.error.message } }
+}
+
 /**
  * Protocol object with definition and metadata.
  */
 export interface Protocol<T extends ProtocolDef> {
 	/** The protocol definition */
 	_def: T
-	/** Get endpoint definition by name */
-	getEndpoint<K extends keyof T>(name: K): T[K]
-	/** Check if endpoint is a method */
-	isMethod(name: keyof T): boolean
-	/** Check if endpoint is a notification */
-	isNotification(name: keyof T): boolean
-	/** Get all method names */
-	getMethodNames(): (keyof T)[]
 	/** Get all notification names */
 	getNotificationNames(): (keyof T)[]
-	/** Validate input for an endpoint */
+	/** Validate input for a notification */
 	validateInput<K extends keyof T>(name: K, input: unknown): SafeParseResult<InferInput<T[K]>>
-	/** Validate output for a method endpoint */
-	validateOutput<K extends keyof T>(name: K, output: unknown): SafeParseResult<unknown>
 }
 
 /**
- * Define a protocol with typed endpoints.
+ * Define a protocol with typed notifications.
  *
  * @example
  * ```typescript
- * const clientProtocol = defineProtocol({
- *   subscribe: method({
- *     input: z.object({ sessionId: z.string() }),
- *     output: z.void(),
- *     error: z.object({ code: z.literal('SESSION_NOT_FOUND') }),
- *   }),
- *
- *   userMessage: method({
- *     input: z.object({ sessionId: z.string(), content: z.string() }),
- *     output: z.object({ messageId: z.string() }),
- *     error: z.object({ code: z.literal('AGENT_BUSY') }),
- *   }),
- * });
- *
  * const serverProtocol = defineProtocol({
  *   agentMessage: notification({
  *     input: z.object({ sessionId: z.string(), content: z.string() }),
@@ -278,71 +154,12 @@ export function defineProtocol<T extends ProtocolDef>(def: T): Protocol<T> {
 	return {
 		_def: def,
 
-		getEndpoint<K extends keyof T>(name: K): T[K] {
-			return def[name]
-		},
-
-		isMethod(name: keyof T): boolean {
-			const endpoint = def[name]
-			return endpoint?._type === 'method'
-		},
-
-		isNotification(name: keyof T): boolean {
-			const endpoint = def[name]
-			return endpoint?._type === 'notification'
-		},
-
-		getMethodNames(): (keyof T)[] {
-			return Object.keys(def).filter((key) => def[key]._type === 'method') as (keyof T)[]
-		},
-
 		getNotificationNames(): (keyof T)[] {
-			return Object.keys(def).filter((key) => def[key]._type === 'notification') as (keyof T)[]
+			return Object.keys(def)
 		},
 
 		validateInput<K extends keyof T>(name: K, input: unknown): SafeParseResult<InferInput<T[K]>> {
-			const endpoint = def[name]
-			const result = endpoint.input.safeParse(input)
-			if (result.success) {
-				return { success: true, data: result.data as InferInput<T[K]> }
-			}
-			return { success: false, error: { message: result.error.message } }
-		},
-
-		validateOutput<K extends keyof T>(name: K, output: unknown): SafeParseResult<unknown> {
-			const endpoint = def[name]
-			if (endpoint._type !== 'method') {
-				throw new Error(`Endpoint ${String(name)} is not a method`)
-			}
-			const result = endpoint.output.safeParse(output)
-			if (result.success) {
-				return { success: true, data: result.data }
-			}
-			return { success: false, error: { message: result.error.message } }
+			return safeParseWith<T[K]['input']>(def[name].input, input)
 		},
 	}
 }
-
-// ============================================================================
-// Type Extraction Helpers
-// ============================================================================
-
-/**
- * Extract the protocol definition type from a Protocol.
- */
-export type ExtractProtocolDef<T> = T extends Protocol<infer P> ? P : never
-
-/**
- * Create a typed handlers object type for a protocol.
- */
-export type HandlersFor<T extends Protocol<ProtocolDef>> = ProtocolHandlers<ExtractProtocolDef<T>>
-
-/**
- * Create a typed caller object type for a protocol.
- */
-export type CallerFor<T extends Protocol<ProtocolDef>> = ProtocolCaller<ExtractProtocolDef<T>>
-
-/**
- * Create a typed notifier object type for a protocol.
- */
-export type NotifierFor<T extends Protocol<ProtocolDef>> = ProtocolNotifier<ExtractProtocolDef<T>>

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * @roj-ai/transport
  *
- * Platform-agnostic WebSocket transport infrastructure with RPC-like protocol API.
+ * Platform-agnostic WebSocket transport infrastructure with a typed notification protocol API.
  */
 
 // ============================================================================
@@ -9,33 +9,19 @@
 // ============================================================================
 
 // Protocol Definition API
-export { defineProtocol, method, notification } from './core/protocol.js'
+export { defineProtocol, notification } from './core/protocol.js'
 export type {
-	CallerFor,
-	EndpointDef,
-	EndpointHandler,
-	ExtractProtocolDef,
 	HandlerContext,
-	HandlersFor,
-	InferError,
 	InferInput,
-	InferOutput,
-	IsMethod,
-	IsNotification,
-	MethodCaller,
-	MethodDef,
-	MethodHandler,
-	MethodOptions,
 	NotificationDef,
 	NotificationHandler,
 	NotificationNotifier,
 	NotificationOptions,
-	NotifierFor,
 	Protocol,
-	ProtocolCaller,
 	ProtocolDef,
 	ProtocolHandlers,
 	ProtocolNotifier,
+	SafeParseResult,
 } from './core/protocol.js'
 
 // Result Type

package/src/server/index.ts

@@ -15,12 +15,12 @@ export type {
 	ConnectionState,
 	HandlerContext,
 	Protocol,
-	ProtocolCaller,
 	ProtocolDef,
 	ProtocolHandlers,
 	ProtocolNotifier,
+	SafeParseResult,
 	TransportEvent,
 	TransportEventListener,
 } from '../core/index.js'
 
-export { defineProtocol, method, notification } from '../core/index.js'
+export { defineProtocol, notification } from '../core/index.js'