@nmtjs/protocol 0.6.0

package/lib/common/binary.ts

@@ -0,0 +1,60 @@
+// TODO: get rid of lib DOM somehow...
+/// <reference lib="dom" />
+
+const utf8decoder = new TextDecoder()
+const utf8encoder = new TextEncoder()
+
+export type BinaryTypes = {
+  Int8: number
+  Int16: number
+  Int32: number
+  Uint8: number
+  Uint16: number
+  Uint32: number
+  Float32: number
+  Float64: number
+  BigInt64: bigint
+  BigUint64: bigint
+}
+
+export const encodeNumber = <T extends keyof BinaryTypes>(
+  value: BinaryTypes[T],
+  type: T,
+  littleEndian = false,
+) => {
+  const bytesNeeded = globalThis[`${type}Array`].BYTES_PER_ELEMENT
+  const ab = new ArrayBuffer(bytesNeeded)
+  const dv = new DataView(ab)
+  dv[`set${type}`](0, value as never, littleEndian)
+  return ab
+}
+
+export const decodeNumber = <T extends keyof BinaryTypes>(
+  buffer: ArrayBuffer,
+  type: T,
+  offset = 0,
+  littleEndian = false,
+): BinaryTypes[T] => {
+  const view = new DataView(buffer)
+  return view[`get${type}`](offset, littleEndian) as BinaryTypes[T]
+}
+
+export const encodeText = (text: string) =>
+  new Uint8Array(utf8encoder.encode(text)).buffer as ArrayBuffer
+
+export const decodeText = (buffer: Parameters<typeof utf8decoder.decode>[0]) =>
+  utf8decoder.decode(buffer)
+
+export const concat = (...buffers: ArrayBuffer[]) => {
+  const totalLength = buffers.reduce(
+    (acc, buffer) => acc + buffer.byteLength,
+    0,
+  )
+  const view = new Uint8Array(totalLength)
+  let offset = 0
+  for (const buffer of buffers) {
+    view.set(new Uint8Array(buffer), offset)
+    offset += buffer.byteLength
+  }
+  return view.buffer
+}

package/lib/common/blob.ts

@@ -0,0 +1,70 @@
+export type ProtocolBlobMetadata = {
+  type: string
+  size: number
+  filename?: string
+}
+
+export interface ProtocolBlobInterface {
+  readonly metadata: ProtocolBlobMetadata
+}
+
+export class ProtocolBlob implements ProtocolBlobInterface {
+  public readonly metadata: ProtocolBlobMetadata
+  public readonly source: any
+
+  constructor(
+    source: any,
+    size = -1,
+    type = 'application/octet-stream',
+    filename?: string,
+  ) {
+    if (size < -1 || size === 0) throw new Error('Blob size is invalid')
+
+    this.source = source
+    this.metadata = {
+      size,
+      type,
+      filename,
+    }
+  }
+
+  static from(
+    source: any,
+    metadata: {
+      size?: number
+      type?: string
+      filename?: string
+    } = {},
+  ) {
+    let _source: any = undefined
+
+    if (source instanceof globalThis.ReadableStream) {
+      _source = source
+    } else if ('File' in globalThis && source instanceof globalThis.File) {
+      _source = source.stream()
+      metadata.size = source.size
+      metadata.filename = source.name
+    } else if (source instanceof globalThis.Blob) {
+      _source = source.stream()
+      metadata.size = source.size
+    } else if (typeof source === 'string') {
+      const blob = new Blob([source])
+      _source = blob.stream()
+      metadata.size = blob.size
+      metadata.type = metadata.type || 'text/plain'
+    } else if (source instanceof globalThis.ArrayBuffer) {
+      const blob = new Blob([source])
+      _source = blob.stream()
+      metadata.size = blob.size
+    } else {
+      _source = source
+    }
+
+    return new ProtocolBlob(
+      _source,
+      metadata.size,
+      metadata.type,
+      metadata.filename,
+    )
+  }
+}

package/lib/common/enums.ts

@@ -0,0 +1,46 @@
+export enum ClientMessageType {
+  Rpc = 10,
+  RpcAbort = 11,
+  RpcStreamAbort = 12,
+
+  ClientStreamPush = 20,
+  ClientStreamEnd = 21,
+  ClientStreamAbort = 22,
+  ServerStreamAbort = 23,
+  ServerStreamPull = 24,
+}
+
+export enum ServerMessageType {
+  Event = 1,
+
+  RpcResponse = 10,
+  RpcStreamResponse = 11,
+  RpcStreamChunk = 12,
+  RpcStreamAbort = 13,
+
+  ServerStreamPush = 20,
+  ServerStreamEnd = 21,
+  ServerStreamAbort = 22,
+  ClientStreamAbort = 23,
+  ClientStreamPull = 24,
+}
+
+export enum TransportType {
+  Bidirectional = 'Bidirectional',
+  Unidirectional = 'Unidirectional',
+}
+
+export enum ErrorCode {
+  ValidationError = 'ValidationError',
+  BadRequest = 'BadRequest',
+  NotFound = 'NotFound',
+  Forbidden = 'Forbidden',
+  Unauthorized = 'Unauthorized',
+  InternalServerError = 'InternalServerError',
+  NotAcceptable = 'NotAcceptable',
+  RequestTimeout = 'RequestTimeout',
+  GatewayTimeout = 'GatewayTimeout',
+  ServiceUnavailable = 'ServiceUnavailable',
+  ClientRequestError = 'ClientRequestError',
+  ConnectionError = 'ConnectionError',
+}

package/lib/common/index.ts

@@ -0,0 +1,4 @@
+export * from './types.ts'
+export * from './enums.ts'
+export * from './binary.ts'
+export * from './blob.ts'

package/lib/common/types.ts

@@ -0,0 +1,64 @@
+import type { ProtocolServerBlobStream } from '../client/stream.ts'
+import type {
+  ProtocolBlob,
+  ProtocolBlobInterface,
+  ProtocolBlobMetadata,
+} from './blob.ts'
+
+export type ProtocolRPC = {
+  callId: number
+  namespace: string
+  procedure: string
+  payload: any
+}
+
+export type ProtocolRPCResponse =
+  | {
+      callId: number
+      error: any
+      payload?: never
+    }
+  | {
+      callId: number
+      payload: any
+      error?: never
+    }
+
+export interface EncodeRPCContext {
+  getStream: (id: number) => any
+  addStream: (blob: ProtocolBlob) => {
+    id: number
+    metadata: ProtocolBlobMetadata
+  }
+}
+
+export interface DecodeRPCContext {
+  getStream: (id: number) => any
+  addStream: (id: number, metadata: ProtocolBlobMetadata) => any
+}
+
+export interface BaseClientDecoder {
+  decode(buffer: ArrayBuffer): any
+  decodeRPC(buffer: ArrayBuffer, context: DecodeRPCContext): ProtocolRPCResponse
+}
+
+export interface BaseClientEncoder {
+  encode(data: any): ArrayBuffer
+  encodeRPC(rpc: ProtocolRPC, context: EncodeRPCContext): ArrayBuffer
+}
+
+export type InputType<T> = T extends any[]
+  ? InputType<T[number]>[]
+  : T extends ProtocolBlobInterface
+    ? ProtocolBlob
+    : T extends object
+      ? { [K in keyof T]: InputType<T[K]> }
+      : T
+
+export type OutputType<T> = T extends any[]
+  ? OutputType<T[number]>[]
+  : T extends ProtocolBlobInterface
+    ? ProtocolServerBlobStream
+    : T extends object
+      ? { [K in keyof T]: OutputType<T[K]> }
+      : T

package/lib/server/api.ts

@@ -0,0 +1,47 @@
+import type { Container } from '@nmtjs/core'
+import type { Hook } from '@nmtjs/core'
+import type { Connection } from './connection.ts'
+
+export type ProtocolApiCallOptions = {
+  connection: Connection
+  namespace: string
+  procedure: string
+  container: Container
+  payload: any
+  signal: AbortSignal
+}
+
+export type ProtocolAnyIterable<T> =
+  | (() => AsyncGenerator<T>)
+  // | (() => Generator<T>)
+  | AsyncIterable<T>
+// | Iterable<T>
+
+export interface ProtocolApiCallBaseResult {
+  output: unknown
+}
+export interface ProtocolApiCallSubscriptionResult
+  extends ProtocolApiCallBaseResult {
+  subscription: never
+}
+
+export interface ProtocolApiCallIterableResult
+  extends ProtocolApiCallBaseResult {
+  iterable: ProtocolAnyIterable<unknown>
+}
+
+export type ProtocolApiCallResult =
+  | ProtocolApiCallBaseResult
+  | ProtocolApiCallSubscriptionResult
+  | ProtocolApiCallIterableResult
+
+export interface ProtocolApi {
+  call(options: ProtocolApiCallOptions): Promise<ProtocolApiCallResult>
+}
+
+declare module '@nmtjs/core' {
+  export interface HookType {
+    [Hook.OnConnect]: (connection: Connection) => any
+    [Hook.OnDisconnect]: (connection: Connection) => any
+  }
+}

package/lib/server/connection.ts

@@ -0,0 +1,57 @@
+import { randomUUID } from 'node:crypto'
+// import type { TAnyEventContract } from '@nmtjs/contract'
+import type { InteractivePromise } from '@nmtjs/common'
+import type { Container } from '@nmtjs/core'
+import type { ProtocolApiCallResult } from './api.ts'
+import type { BaseServerDecoder, BaseServerEncoder } from './format.ts'
+import type { ProtocolClientStream, ProtocolServerStream } from './stream.ts'
+
+// export type NotifyFn = <T extends TAnyEventContract>(
+//   connection: Connection,
+//   contract: T,
+//   payload: t.infer.input.decoded<T['payload']>,
+// ) => Promise<boolean>
+
+// export type ConnectionNotifyFn = (
+//   contract: TAnyEventContract,
+//   payload: unknown,
+// ) => Promise<boolean>
+
+export type ConnectionOptions<Data = unknown> = {
+  id?: string
+  data: Data
+}
+
+export class Connection<Data = unknown> {
+  readonly id: string
+  readonly data: Data
+
+  constructor(options: ConnectionOptions<Data>) {
+    this.id = options.id ?? randomUUID()
+    this.data = options.data
+  }
+}
+
+export type ConnectionCall<T = unknown> = InteractivePromise<T> & {
+  abort: AbortController['abort']
+}
+
+export class ConnectionContext {
+  streamId = 1
+  calls = new Map<number, ConnectionCall<ProtocolApiCallResult>>()
+  clientStreams = new Map<number, ProtocolClientStream>()
+  serverStreams = new Map<number, ProtocolServerStream>()
+  container: Container
+  format: {
+    encoder: BaseServerEncoder
+    decoder: BaseServerDecoder
+  }
+
+  constructor(
+    container: ConnectionContext['container'],
+    format: ConnectionContext['format'],
+  ) {
+    this.container = container
+    this.format = format
+  }
+}

package/lib/server/constants.ts

@@ -0,0 +1,4 @@
+export const kTransportPlugin: unique symbol = Symbol.for(
+  'neemata:TransportPluginKey',
+)
+export type kTransportPlugin = typeof kTransportPlugin

package/lib/server/format.ts

@@ -0,0 +1,107 @@
+import { type Pattern, match } from '@nmtjs/core'
+import type {
+  DecodeRPCContext,
+  EncodeRPCContext,
+  ProtocolRPC,
+  ProtocolRPCResponse,
+} from '../common/types.ts'
+
+export interface BaseServerDecoder {
+  accept: Pattern[]
+  decode(buffer: ArrayBuffer): any
+  decodeRPC(buffer: ArrayBuffer, context: DecodeRPCContext): ProtocolRPC
+}
+
+export interface BaseServerEncoder {
+  contentType: string
+  encode(data: any): ArrayBuffer
+  encodeRPC(rpc: ProtocolRPCResponse, context: EncodeRPCContext): ArrayBuffer
+}
+
+export abstract class BaseServerFormat
+  implements BaseServerDecoder, BaseServerEncoder
+{
+  abstract accept: Pattern[]
+  abstract contentType: string
+
+  abstract encode(data: any): ArrayBuffer
+  abstract encodeRPC(
+    rpc: ProtocolRPCResponse,
+    context: EncodeRPCContext,
+  ): ArrayBuffer
+  abstract decode(buffer: ArrayBuffer): any
+  abstract decodeRPC(
+    buffer: ArrayBuffer,
+    context: DecodeRPCContext,
+  ): ProtocolRPC
+}
+
+export const parseContentTypes = (types: string) => {
+  if (types === '*/*') return ['*/*']
+  return types
+    .split(',')
+    .map((t) => {
+      const [type, ...rest] = t.split(';')
+      const params = new Map(
+        rest.map((p) =>
+          p
+            .trim()
+            .split('=')
+            .slice(0, 2)
+            .map((p) => p.trim()),
+        ) as [string, string][],
+      )
+      return {
+        type,
+        q: params.has('q') ? Number.parseFloat(params.get('q')!) : 1,
+      }
+    })
+    .sort((a, b) => {
+      if (a.type === '*/*') return 1
+      if (b.type === '*/*') return -1
+      return b.q - a.q ? -1 : 1
+    })
+    .map((t) => t.type)
+}
+
+export class Format {
+  decoders = new Map<Pattern, BaseServerDecoder>()
+  encoders = new Map<Pattern, BaseServerEncoder>()
+
+  constructor(formats: BaseServerFormat[]) {
+    for (const format of formats) {
+      this.encoders.set(format.contentType, format)
+      for (const acceptType of format.accept) {
+        this.decoders.set(acceptType, format)
+      }
+    }
+  }
+
+  supportsDecoder(contentType: string, throwIfUnsupported = false) {
+    return this.supports(this.decoders, contentType, throwIfUnsupported)
+  }
+
+  supportsEncoder(contentType: string, throwIfUnsupported = false) {
+    return this.supports(this.encoders, contentType, throwIfUnsupported)
+  }
+
+  private supports<T extends BaseServerEncoder | BaseServerDecoder>(
+    formats: Map<Pattern, T>,
+    contentType: string,
+    throwIfUnsupported = false,
+  ): T | null {
+    // TODO: Use node:utils.MIMEType (not implemented yet in Deno and Bun yet)
+    const types = parseContentTypes(contentType)
+
+    for (const type of types) {
+      for (const [pattern, format] of formats) {
+        if (type === '*/*' || match(type, pattern)) return format
+      }
+    }
+
+    if (throwIfUnsupported)
+      throw new Error(`No supported format found: ${contentType}`)
+
+    return null
+  }
+}

package/lib/server/index.ts

@@ -0,0 +1,10 @@
+export * from './api.ts'
+export * from './connection.ts'
+export * from './constants.ts'
+export * from './injectables.ts'
+export * from './format.ts'
+export * from './protocol.ts'
+export * from './registry.ts'
+export * from './stream.ts'
+export * from './transport.ts'
+export * from './utils.ts'

package/lib/server/injectables.ts

@@ -0,0 +1,51 @@
+import {
+  Scope,
+  createFactoryInjectable,
+  createLazyInjectable,
+} from '@nmtjs/core'
+
+const connection = createLazyInjectable<unknown, Scope.Connection>(
+  Scope.Connection,
+  'RPC connection',
+)
+
+const connectionData = createLazyInjectable<unknown, Scope.Connection>(
+  Scope.Connection,
+  "RPC connection's data",
+)
+
+const transportStopSignal = createLazyInjectable<AbortSignal>(
+  Scope.Global,
+  'Transport stop signal',
+)
+
+const rpcClientAbortSignal = createLazyInjectable<AbortSignal, Scope.Call>(
+  Scope.Call,
+  'RPC client abort signal',
+)
+
+const rpcTimeoutSignal = createLazyInjectable<AbortSignal, Scope.Call>(
+  Scope.Call,
+  'RPC timeout signal',
+)
+
+const rpcAbortSignal = createFactoryInjectable(
+  {
+    dependencies: {
+      rpcTimeoutSignal,
+      rpcClientAbortSignal,
+      transportStopSignal,
+    },
+    factory: (ctx) => AbortSignal.any(Object.values(ctx)),
+  },
+  'Any RPC abort signal',
+)
+
+export const ProtocolInjectables = {
+  connection,
+  connectionData,
+  transportStopSignal,
+  rpcClientAbortSignal,
+  rpcTimeoutSignal,
+  rpcAbortSignal,
+} as const