@nmtjs/protocol 0.15.0-beta.37 → 0.15.0-beta.39

package/src/client/versions/v1.ts

@@ -0,0 +1,205 @@
+import type { BaseProtocolError } from '../../common/types.ts'
+import type { ClientMessageTypePayload, MessageContext } from '../protocol.ts'
+import {
+  decodeNumber,
+  decodeText,
+  encodeNumber,
+  encodeText,
+} from '../../common/binary.ts'
+import {
+  ClientMessageType,
+  MessageByteLength,
+  ProtocolVersion,
+  ServerMessageType,
+} from '../../common/enums.ts'
+import { ProtocolVersionInterface } from '../protocol.ts'
+
+export class ProtocolVersion1 extends ProtocolVersionInterface {
+  version = ProtocolVersion.v1
+
+  decodeMessage(context: MessageContext, buffer: Uint8Array) {
+    const messageType = decodeNumber(buffer, 'Uint8')
+    const payload = buffer.subarray(MessageByteLength.MessageType)
+    switch (messageType) {
+      // case ServerMessageType.Event: {
+      //   const { event, data } = context.decoder.decode(payload)
+      //   return { type: messageType, event, data }
+      // }
+      case ServerMessageType.RpcResponse: {
+        const callId = decodeNumber(payload, 'Uint32')
+        const isError = decodeNumber(payload, 'Uint8', MessageByteLength.CallId)
+        const dataPayload = payload.subarray(
+          MessageByteLength.CallId + MessageByteLength.MessageError,
+        )
+
+        if (isError) {
+          const error = context.decoder.decode(dataPayload) as BaseProtocolError
+          return { type: messageType, callId, error }
+        } else {
+          const result = context.decoder.decodeRPC(dataPayload, {
+            addStream: (streamId, metadata) => {
+              return context.addServerStream(streamId, metadata)
+            },
+          })
+          return { type: messageType, callId, result }
+        }
+      }
+      case ServerMessageType.RpcStreamResponse: {
+        const callId = decodeNumber(payload, 'Uint32')
+        const errorPayload = payload.subarray(MessageByteLength.CallId)
+        const error =
+          errorPayload.byteLength > 0
+            ? (context.decoder.decode(errorPayload) as
+                | BaseProtocolError
+                | undefined)
+            : undefined
+        return { type: messageType, callId, error }
+      }
+      case ServerMessageType.RpcStreamChunk: {
+        const callId = decodeNumber(payload, 'Uint32')
+        const chunk = payload.subarray(MessageByteLength.CallId)
+        return { type: messageType, callId, chunk }
+      }
+      case ServerMessageType.RpcStreamEnd: {
+        const callId = decodeNumber(payload, 'Uint32')
+        return { type: messageType, callId }
+      }
+      case ServerMessageType.RpcStreamAbort: {
+        const callId = decodeNumber(payload, 'Uint32')
+        const reasonPayload = payload.subarray(MessageByteLength.CallId)
+        const reason =
+          reasonPayload.byteLength > 0 ? decodeText(reasonPayload) : undefined
+        return { type: messageType, callId, reason }
+      }
+      case ServerMessageType.ClientStreamPull: {
+        const streamId = decodeNumber(payload, 'Uint32')
+        const size = decodeNumber(payload, 'Uint32', MessageByteLength.StreamId)
+        return { type: messageType, streamId, size }
+      }
+      case ServerMessageType.ClientStreamAbort: {
+        const streamId = decodeNumber(payload, 'Uint32')
+        const reasonPayload = payload.subarray(MessageByteLength.StreamId)
+        const reason =
+          reasonPayload.byteLength > 0 ? decodeText(reasonPayload) : undefined
+
+        return { type: messageType, streamId, reason }
+      }
+      case ServerMessageType.ServerStreamPush: {
+        const streamId = decodeNumber(payload, 'Uint32')
+        const chunk = payload.subarray(MessageByteLength.StreamId)
+        return { type: messageType, streamId, chunk }
+      }
+      case ServerMessageType.ServerStreamEnd: {
+        const streamId = decodeNumber(payload, 'Uint32')
+        const reasonPayload = payload.subarray(MessageByteLength.StreamId)
+        const reason =
+          reasonPayload.byteLength > 0 ? decodeText(reasonPayload) : undefined
+
+        return { type: messageType, streamId, reason }
+      }
+      case ServerMessageType.ServerStreamAbort: {
+        const streamId = decodeNumber(payload, 'Uint32')
+        const reasonPayload = payload.subarray(MessageByteLength.StreamId)
+        const reason =
+          reasonPayload.byteLength > 0 ? decodeText(reasonPayload) : undefined
+
+        return { type: messageType, streamId, reason }
+      }
+
+      default:
+        throw new Error(`Unsupported message type: ${messageType}`)
+    }
+  }
+
+  encodeMessage<T extends ClientMessageType>(
+    context: MessageContext,
+    messageType: T,
+    payload: ClientMessageTypePayload[T],
+  ) {
+    switch (messageType) {
+      case ClientMessageType.Rpc: {
+        const {
+          callId,
+          procedure,
+          payload: rpcPayload,
+        } = payload as ClientMessageTypePayload[ClientMessageType.Rpc]
+        const procedureBuffer = encodeText(procedure)
+        return this.encode(
+          encodeNumber(messageType, 'Uint8'),
+          encodeNumber(callId, 'Uint32'),
+          encodeNumber(procedureBuffer.byteLength, 'Uint16'),
+          procedureBuffer,
+          context.encoder.encodeRPC(rpcPayload, {
+            addStream: (blob) => context.addClientStream(blob),
+          }),
+        )
+      }
+      case ClientMessageType.RpcAbort: {
+        const { callId, reason } =
+          payload as ClientMessageTypePayload[ClientMessageType.RpcAbort]
+
+        return this.encode(
+          encodeNumber(messageType, 'Uint8'),
+          encodeNumber(callId, 'Uint32'),
+          reason ? encodeText(reason) : new Uint8Array(0),
+        )
+      }
+      case ClientMessageType.RpcPull: {
+        const { callId } =
+          payload as ClientMessageTypePayload[ClientMessageType.RpcPull]
+
+        return this.encode(
+          encodeNumber(messageType, 'Uint8'),
+          encodeNumber(callId, 'Uint32'),
+        )
+      }
+      case ClientMessageType.ClientStreamPush: {
+        const { streamId, chunk } =
+          payload as ClientMessageTypePayload[ClientMessageType.ClientStreamPush]
+        return this.encode(
+          encodeNumber(messageType, 'Uint8'),
+          encodeNumber(streamId, 'Uint32'),
+          chunk,
+        )
+      }
+      case ClientMessageType.ClientStreamEnd: {
+        const { streamId } =
+          payload as ClientMessageTypePayload[ClientMessageType.ClientStreamEnd]
+        return this.encode(
+          encodeNumber(messageType, 'Uint8'),
+          encodeNumber(streamId, 'Uint32'),
+        )
+      }
+      case ClientMessageType.ClientStreamAbort: {
+        const { streamId, reason } =
+          payload as ClientMessageTypePayload[ClientMessageType.ClientStreamAbort]
+        return this.encode(
+          encodeNumber(messageType, 'Uint8'),
+          encodeNumber(streamId, 'Uint32'),
+          reason ? encodeText(reason) : new Uint8Array(0),
+        )
+      }
+      case ClientMessageType.ServerStreamPull: {
+        const { streamId, size } =
+          payload as ClientMessageTypePayload[ClientMessageType.ServerStreamPull]
+        return this.encode(
+          encodeNumber(messageType, 'Uint8'),
+          encodeNumber(streamId, 'Uint32'),
+          encodeNumber(size, 'Uint32'),
+        )
+      }
+      case ClientMessageType.ServerStreamAbort: {
+        const { streamId, reason } =
+          payload as ClientMessageTypePayload[ClientMessageType.ServerStreamAbort]
+        return this.encode(
+          encodeNumber(messageType, 'Uint8'),
+          encodeNumber(streamId, 'Uint32'),
+          reason ? encodeText(reason) : new Uint8Array(0),
+        )
+      }
+
+      default:
+        throw new Error(`Unsupported message type: ${messageType}`)
+    }
+  }
+}

package/src/common/binary.ts

@@ -0,0 +1,70 @@
+// 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 = true,
+) => {
+  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 | ArrayBufferView,
+  type: T,
+  offset = 0,
+  littleEndian = true,
+): BinaryTypes[T] => {
+  const ab = buffer instanceof ArrayBuffer ? buffer : buffer.buffer
+  const baseOffset = buffer instanceof ArrayBuffer ? 0 : buffer.byteOffset
+  const view = new DataView(ab)
+  return view[`get${type}`](baseOffset + offset, littleEndian) as BinaryTypes[T]
+}
+
+export const encodeText = (text: string) => utf8encoder.encode(text)
+
+export const decodeText = (buffer: Parameters<typeof utf8decoder.decode>[0]) =>
+  utf8decoder.decode(buffer)
+
+export const concat = (...buffers: (ArrayBuffer | ArrayBufferView)[]) => {
+  let totalLength = 0
+  for (const buffer of buffers) totalLength += buffer.byteLength
+  const view = new Uint8Array(totalLength)
+  let offset = 0
+  for (const buffer of buffers) {
+    const chunk =
+      buffer instanceof ArrayBuffer
+        ? new Uint8Array(buffer)
+        : new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)
+    view.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return view
+}
+
+export const UTF8Transform = () =>
+  new TransformStream<string, Uint8Array>({
+    transform(chunk, controller) {
+      controller.enqueue(encodeText(chunk))
+    },
+  })

package/src/common/blob.ts

@@ -0,0 +1,94 @@
+import { kBlobKey } from './constants.ts'
+
+export type ProtocolBlobMetadata = {
+  type: string
+  size?: number | undefined
+  filename?: string | undefined
+}
+
+export interface ProtocolBlobInterface {
+  readonly metadata: ProtocolBlobMetadata
+  readonly [kBlobKey]: any
+}
+
+export class ProtocolBlob implements ProtocolBlobInterface {
+  [kBlobKey]: true = true
+
+  public readonly source: any
+  public readonly metadata: ProtocolBlobMetadata
+  public readonly encode?: (metadata: ProtocolBlobMetadata) => unknown
+  public readonly toJSON?: () => unknown
+
+  constructor({
+    source,
+    encode,
+    size,
+    type = 'application/octet-stream',
+    filename,
+  }: {
+    source: any
+    encode?: () => unknown
+    size?: number
+    type?: string
+    filename?: string
+  }) {
+    if (typeof size !== 'undefined' && size <= 0)
+      throw new Error('Blob size is invalid')
+
+    this.encode = encode
+    this.source = source
+    this.metadata = { size, type, filename }
+    if (encode) {
+      Object.defineProperty(this, 'toJSON', {
+        configurable: false,
+        enumerable: false,
+        writable: false,
+        value: encode,
+      })
+    }
+  }
+
+  static from(
+    _source: any,
+    _metadata: { size?: number; type?: string; filename?: string } = {},
+    _encode?: (metadata: ProtocolBlobMetadata) => unknown,
+  ) {
+    let source: any
+    const metadata = { type: 'application/octet-stream', ..._metadata }
+
+    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
+      metadata.type ??= _source.type
+    } else if (typeof _source === 'string') {
+      const blob = new Blob([_source])
+      source = blob.stream()
+      metadata.size ??= blob.size
+      metadata.type ??= 'text/plain'
+    } else if (globalThis.ArrayBuffer.isView(_source)) {
+      const blob = new Blob([_source as ArrayBufferView<ArrayBuffer>])
+      source = blob.stream()
+      metadata.size ??= blob.size
+    } 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,
+      encode: _encode?.bind(null, metadata),
+      size: metadata.size,
+      type: metadata.type,
+      filename: metadata.filename,
+    })
+  }
+}

package/src/common/constants.ts

@@ -0,0 +1,2 @@
+export const kBlobKey: unique symbol = Symbol.for('neemata:blobKey')
+export type kBlobKey = typeof kBlobKey

package/src/common/enums.ts

@@ -0,0 +1,62 @@
+export enum ProtocolVersion {
+  v1 = 1,
+}
+
+export enum ClientMessageType {
+  Rpc = 10,
+  RpcAbort = 11,
+  RpcPull = 12,
+
+  ClientStreamPush = 20,
+  ClientStreamEnd = 21,
+  ClientStreamAbort = 22,
+
+  ServerStreamAbort = 33,
+  ServerStreamPull = 34,
+}
+
+export enum ServerMessageType {
+  // Event = 1,
+
+  RpcResponse = 10,
+  RpcStreamResponse = 11,
+  RpcStreamChunk = 12,
+  RpcStreamEnd = 13,
+  RpcStreamAbort = 14,
+
+  ServerStreamPush = 20,
+  ServerStreamEnd = 21,
+  ServerStreamAbort = 22,
+
+  ClientStreamAbort = 33,
+  ClientStreamPull = 34,
+}
+
+export enum ConnectionType {
+  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',
+}
+
+export enum MessageByteLength {
+  MessageType = 1,
+  MessageError = 1,
+  ProcedureLength = 2,
+  CallId = 4,
+  StreamId = 4,
+  ChunkSize = 4,
+}

package/src/common/index.ts

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

package/src/common/types.ts

@@ -0,0 +1,18 @@
+import type { ProtocolBlobMetadata } from './blob.ts'
+
+type Stream = any
+
+export interface BaseProtocolError {
+  code: string
+  message: string
+  data?: any
+}
+
+export type ProtocolRPCPayload = unknown
+export type ProtocolRPCResponse = unknown
+
+export type EncodeRPCStreams = Record<number, ProtocolBlobMetadata>
+
+export interface DecodeRPCContext<T = Stream> {
+  addStream: (id: number, metadata: ProtocolBlobMetadata) => T
+}

package/src/common/utils.ts

@@ -0,0 +1,12 @@
+import type { ProtocolBlobInterface } from './blob.ts'
+import { kBlobKey } from './constants.ts'
+
+export const isBlobInterface = <T extends ProtocolBlobInterface>(
+  value: any,
+): value is T => {
+  return (
+    value &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    kBlobKey in value
+  )
+}

package/src/server/format.ts

@@ -0,0 +1,117 @@
+import type { Pattern } from '@nmtjs/common'
+import { match } from '@nmtjs/common'
+
+import type { ProtocolBlobMetadata } from '../common/blob.ts'
+import type {
+  DecodeRPCContext,
+  EncodeRPCStreams,
+  ProtocolRPCPayload,
+} from '../common/types.ts'
+import type { ProtocolClientStream } from './stream.ts'
+
+export interface BaseServerDecoder {
+  accept: Pattern[]
+  decode(buffer: ArrayBufferView): unknown
+  decodeRPC(
+    buffer: ArrayBufferView,
+    context: DecodeRPCContext<() => ProtocolClientStream>,
+  ): ProtocolRPCPayload
+}
+
+export interface BaseServerEncoder {
+  contentType: string
+  encode(data: unknown): ArrayBufferView
+  encodeRPC(data: unknown, streams: EncodeRPCStreams): ArrayBufferView
+  encodeBlob(streamId: number, metadata: ProtocolBlobMetadata): unknown
+}
+
+export abstract class BaseServerFormat
+  implements BaseServerDecoder, BaseServerEncoder
+{
+  abstract accept: Pattern[]
+  abstract contentType: string
+
+  abstract encode(data: unknown): ArrayBufferView
+  abstract encodeRPC(data: unknown, streams: EncodeRPCStreams): ArrayBufferView
+  abstract encodeBlob(streamId: number, metadata: ProtocolBlobMetadata): unknown
+  abstract decode(buffer: ArrayBufferView): any
+  abstract decodeRPC(
+    buffer: ArrayBufferView,
+    context: DecodeRPCContext<() => ProtocolClientStream>,
+  ): ProtocolRPCPayload
+}
+
+export const parseContentTypes = (types: string) => {
+  const normalized = types.trim()
+  if (normalized === '*/*') return ['*/*']
+  return normalized
+    .split(',')
+    .map((t) => t.trim())
+    .map((t) => {
+      const [rawType, ...rest] = t.split(';')
+      const params = new Map(
+        rest.map((p) =>
+          p
+            .trim()
+            .split('=')
+            .slice(0, 2)
+            .map((part) => part.trim()),
+        ) as [string, string][],
+      )
+      return {
+        type: rawType.trim(),
+        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
+    })
+    .map((t) => t.type)
+}
+
+export class ProtocolFormats {
+  decoders = new Map<Pattern, BaseServerDecoder>()
+  encoders = new Map<Pattern, BaseServerEncoder>()
+
+  default: BaseServerFormat
+
+  constructor(formats: [BaseServerFormat, ...BaseServerFormat[]]) {
+    this.default = formats[0]
+    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/src/server/index.ts

@@ -0,0 +1,10 @@
+export * from './format.ts'
+export * from './protocol.ts'
+export * from './stream.ts'
+export * from './types.ts'
+export * from './utils.ts'
+
+import { ProtocolVersion } from '../common/enums.ts'
+import { ProtocolVersion1 } from './versions/v1.ts'
+
+export const versions = { [ProtocolVersion.v1]: new ProtocolVersion1() }

package/src/server/protocol.ts

@@ -0,0 +1,97 @@
+import type {
+  ClientMessageType,
+  ProtocolVersion,
+  ServerMessageType,
+} from '../common/enums.ts'
+import type { BaseProtocolError, EncodeRPCStreams } from '../common/types.ts'
+import type { MessageContext } from './types.ts'
+import { concat } from '../common/binary.ts'
+
+export class ProtocolError extends Error implements BaseProtocolError {
+  code: string
+  data?: any
+
+  constructor(code: string, message?: string, data?: any) {
+    super(message)
+    this.code = code
+    this.data = data
+  }
+
+  get message() {
+    return `${this.code} ${super.message}`
+  }
+
+  toString() {
+    return `${this.code} ${this.message}`
+  }
+
+  toJSON() {
+    return { code: this.code, message: this.message, data: this.data }
+  }
+}
+
+export abstract class ProtocolVersionInterface {
+  abstract version: ProtocolVersion
+  abstract decodeMessage(
+    context: MessageContext,
+    buffer: ArrayBufferView,
+  ): {
+    [K in keyof ClientMessageTypePayload]: {
+      type: K
+    } & ClientMessageTypePayload[K]
+  }[keyof ClientMessageTypePayload]
+  abstract encodeMessage<T extends ServerMessageType = ServerMessageType>(
+    context: MessageContext,
+    messageType: T,
+    payload: ServerMessageTypePayload[T],
+  ): ArrayBufferView
+
+  protected encode(
+    ...chunks: (ArrayBuffer | ArrayBufferView)[]
+  ): ArrayBufferView {
+    return concat(...chunks)
+  }
+}
+
+export type ServerMessageTypePayload = {
+  // [ServerMessageType.Event]: { event: string; data: any }
+  [ServerMessageType.RpcResponse]: {
+    callId: number
+    result: any
+    streams: EncodeRPCStreams
+    error: any | null
+  }
+  [ServerMessageType.RpcStreamAbort]: { callId: number; reason?: string }
+  [ServerMessageType.RpcStreamEnd]: { callId: number }
+  [ServerMessageType.RpcStreamChunk]: { callId: number; chunk: ArrayBufferView }
+  [ServerMessageType.RpcStreamResponse]: { callId: number }
+  [ServerMessageType.ClientStreamAbort]: { streamId: number; reason?: string }
+  [ServerMessageType.ClientStreamPull]: { streamId: number; size: number }
+  [ServerMessageType.ServerStreamAbort]: { streamId: number; reason?: string }
+  [ServerMessageType.ServerStreamEnd]: { streamId: number }
+  [ServerMessageType.ServerStreamPush]: {
+    streamId: number
+    chunk: ArrayBufferView
+  }
+}
+
+export type ClientMessageTypePayload = {
+  [ClientMessageType.Rpc]: {
+    rpc: {
+      callId: number
+      procedure: string
+      payload: unknown
+      streams?: EncodeRPCStreams
+    }
+  }
+  [ClientMessageType.RpcPull]: { callId: number }
+  [ClientMessageType.RpcAbort]: { callId: number; reason?: string }
+  [ClientMessageType.ClientStreamPush]: {
+    streamId: number
+    chunk: ArrayBufferView
+  }
+  [ClientMessageType.ClientStreamEnd]: { streamId: number }
+  [ClientMessageType.ClientStreamAbort]: { streamId: number; reason?: string }
+  [ClientMessageType.ServerStreamPull]: { streamId: number; size: number }
+  [ClientMessageType.ServerStreamAbort]: { streamId: number; reason?: string }
+}