api-reference.md

API Reference

Complete API documentation.

Usage

const connection = new window.BareMux.BareMuxConnection('/baremux/worker.js');

await connection.setTransport('/enigma/index.mjs', [{
  base: '/epoxy/index.mjs',
  wisp: 'wss://wisp.example.com/',
  modules: ['/modules/logger.mjs']
}]);

Module Interface

{
  id: string,
  name: string,
  version: string,
  priority?: number,
  enabled?: boolean,
  capabilities: {
    requestInterception?: boolean,
    responseInterception?: boolean,
    websocketInterception?: boolean,
    protocolModification?: boolean
  },
  hooks: {
    onModuleInit?: () => Promise<void> | void,
    onTransportInit?: (innerTransport) => Promise<void> | void,
    onBeforeRequest?: (ctx, next) => Promise<RequestContext | void>,
    onAfterResponse?: (ctx, next) => Promise<ResponseContext | void>,
    onWebSocketConnect?: (ctx, handlers, next) => WebSocketControls | void,
    onWebSocketMessage?: (data, direction, url) => data | void,
    provideMeta?: () => object
  }
}

Hooks

onModuleInit()

Called when module is loaded.

onModuleInit: async () => {
  console.log('Module initialized');
}

onTransportInit(innerTransport)

Called when base transport is ready.

onTransportInit: async (innerTransport) => {
  console.log('Transport ready');
}

onBeforeRequest(ctx, next)

Intercept requests before sending.

Context:

• ctx.remote - URL object
• ctx.method - HTTP method
• ctx.body - BodyInit | null
• ctx.headers - BareHeaders
• ctx.signal - AbortSignal

onBeforeRequest: async (ctx, next) => {
  ctx.headers.set('X-Custom', 'value');
  return await next();
}

onAfterResponse(ctx, next)

Intercept responses after receiving.

Context:

• ctx.remote - URL object
• ctx.body - ReadableStream | ArrayBuffer | Blob | string
• ctx.headers - BareHeaders
• ctx.status - HTTP status code
• ctx.statusText - HTTP status text

onAfterResponse: async (ctx, next) => {
  const response = await next();
  console.log('Status:', response.status);
  return response;
}

onWebSocketConnect(ctx, handlers, next)

Intercept WebSocket connections.

Context:

• ctx.url - URL object
• ctx.protocols - string[]
• ctx.requestHeaders - BareHeaders

Handlers:

• handlers.onopen(protocol)
• handlers.onmessage(data)
• handlers.onclose(code, reason)
• handlers.onerror(error)

onWebSocketConnect: (ctx, handlers, next) => {
  console.log('WS connecting:', ctx.url.href);
  return next();
}

onWebSocketMessage(data, direction, url)

Transform WebSocket messages.

Parameters:

• data - Blob | ArrayBuffer | string
• direction - 'send' | 'receive'
• url - URL object

onWebSocketMessage: (data, direction, url) => {
  console.log(`WS ${direction}:`, data);
  return data;
}

provideMeta()

Expose module metadata.

provideMeta: () => ({
  requestCount: 42
})

Capabilities

capabilities: {
  requestInterception: boolean,   // Has onBeforeRequest
  responseInterception: boolean,  // Has onAfterResponse
  websocketInterception: boolean, // Has onWebSocketMessage
  protocolModification: boolean   // Replaces onWebSocketConnect
}

Priority System

Priority	Category
90-100	Protocol modification
80-89	Security
50-79	Middleware
40-49	Caching
10-39	Observability

Higher priority = First in request chain, Last in response chain.

Default: 50

Module Loading

By Path

modules: ['/modules/logger.mjs']

With Options

modules: [
  { path: '/modules/logger.mjs', options: { verbose: true } }
]

Direct Object

modules: [
  {
    id: 'com.example.logger',
    name: 'Logger',
    version: '1.0.0',
    // ... rest of module
  }
]

Error Handling

onBeforeRequest: async (ctx, next) => {
  try {
    return await next();
  } catch (error) {
    console.error('[Module] Error:', error);
    throw error;
  }
}