Adapters API Reference

interface ServerAdapter {
  readonly name: string;
  listen(port: number, host: string): Promise<void>;
  close(): Promise<void>;
  onRequest(handler: RequestHandler): void;
  getRequestInfo(raw: any): RawRequestInfo;
  sendResponse(
    raw: any,
    statusCode: number,
    headers: Record<string, string>,
    body: Buffer | string
  ): void;
  parseBody(raw: any): Promise<unknown>;
  readonly supportsStreaming?: boolean;
  readonly supportsHTTP2?: boolean;
}

listen(port: number, host: string): Promise<void>

close(): Promise<void>

onRequest(handler: RequestHandler): void

getRequestInfo(raw: any): RawRequestInfo

interface RawRequestInfo {
  method: string;
  url: string;
  headers: Record<string, string | string[]>;
}

sendResponse(
  raw: any,
  statusCode: number,
  headers: Record<string, string>,
  body: Buffer | string
): void

parseBody(raw: any): Promise<unknown>

function createAdapter(
  type?: 'node-http' | 'uwebsockets',
  options?: Record<string, any>
): ServerAdapter

import { createAdapter } from 'ramapi';
 
const adapter = createAdapter('node-http');

const adapter = createAdapter('uwebsockets', {
  idleTimeout: 120,
  maxBackpressure: 1024 * 1024,
});

import { createApp } from 'ramapi';
 
const app = createApp({
  adapter: {
    type: 'uwebsockets',
    options: {
      idleTimeout: 120,
    },
  },
});

function getAvailableAdapters(): string[]

import { getAvailableAdapters } from 'ramapi';
 
const adapters = getAvailableAdapters();
console.log(adapters);
// ['node-http', 'uwebsockets']

interface NodeHTTPOptions {
  keepAlive?: boolean;
  keepAliveTimeout?: number;
  maxHeaderSize?: number;
  insecureHTTPParser?: boolean;
}

import { createApp } from 'ramapi';
 
const app = createApp({
  adapter: {
    type: 'node-http',
    options: {
      keepAlive: true,
      keepAliveTimeout: 5000,
      maxHeaderSize: 16384,
    },
  },
});
 
await app.listen(3000);
// 📡 Using Node.js HTTP adapter
// 🚀 RamAPI server running at http://0.0.0.0:3000

npm install uWebSockets.js

interface UWebSocketsOptions {
  idleTimeout?: number;
  maxBackpressure?: number;
  maxPayloadLength?: number;
  compression?: 0 | 1 | 2;
  ssl?: {
    key_file_name: string;
    cert_file_name: string;
    passphrase?: string;
    dh_params_file_name?: string;
    ssl_prefer_low_memory_usage?: boolean;
  };
}

import { createApp } from 'ramapi';
 
const app = createApp({
  adapter: {
    type: 'uwebsockets',
  },
});
 
await app.listen(3000);
// 🚀 Using uWebSockets adapter for maximum performance
//    💡 Tip: ~2-3x faster than Node.js HTTP
// 🚀 RamAPI server running at http://0.0.0.0:3000

const app = createApp({
  adapter: {
    type: 'uwebsockets',
    options: {
      idleTimeout: 120,
      maxBackpressure: 1024 * 1024,
      maxPayloadLength: 16 * 1024 * 1024,
      compression: 1,
    },
  },
});

const app = createApp({
  adapter: {
    type: 'uwebsockets',
    options: {
      ssl: {
        key_file_name: '/path/to/key.pem',
        cert_file_name: '/path/to/cert.pem',
        passphrase: 'optional_passphrase',
      },
    },
  },
});

import { ServerAdapter, RequestHandler, RawRequestInfo } from 'ramapi';
 
class MyCustomAdapter implements ServerAdapter {
  readonly name = 'my-custom-adapter';
  readonly supportsStreaming = true;
  readonly supportsHTTP2 = false;
 
  private requestHandler?: RequestHandler;
  private server?: any;
 
  async listen(port: number, host: string): Promise<void> {
    this.server = createMyServer();
 
    this.server.on('request', async (req, res) => {
      const requestInfo = this.getRequestInfo({ req, res });
      const response = await this.requestHandler!(requestInfo, { req, res });
 
      this.sendResponse(
        { req, res },
        response.statusCode,
        response.headers,
        response.body
      );
    });
 
    await this.server.listen(port, host);
    console.log(`🚀 My custom adapter listening on ${host}:${port}`);
  }
 
  async close(): Promise<void> {
    if (this.server) {
      await this.server.close();
    }
  }
 
  onRequest(handler: RequestHandler): void {
    this.requestHandler = handler;
  }
 
  getRequestInfo(raw: any): RawRequestInfo {
    const { req } = raw;
    return {
      method: req.method || 'GET',
      url: req.url || '/',
      headers: req.headers,
    };
  }
 
  sendResponse(
    raw: any,
    statusCode: number,
    headers: Record<string, string>,
    body: Buffer | string
  ): void {
    const { res } = raw;
    res.writeHead(statusCode, headers);
    res.end(body);
  }
 
  async parseBody(raw: any): Promise<unknown> {
    const { req } = raw;
    return new Promise((resolve) => {
      let body = '';
      req.on('data', (chunk: Buffer) => {
        body += chunk.toString();
      });
      req.on('end', () => {
        resolve(JSON.parse(body));
      });
    });
  }
}

import { createApp } from 'ramapi';
 
const customAdapter = new MyCustomAdapter();
 
const app = createApp();
// Manually set adapter (advanced usage)

const app = createApp(); // No adapter specified
 
// Selection logic:
// 1. Check if gRPC is enabled → Use Node.js HTTP
// 2. Try uWebSockets → Use if available
// 3. Fallback to Node.js HTTP

🚀 Using uWebSockets adapter for maximum performance
   💡 Tip: ~2-3x faster than Node.js HTTP

📡 Using Node.js HTTP adapter (uWebSockets not available)
   💡 Tip: Install uWebSockets.js for 2-3x performance boost
   npm install uWebSockets.js

📡 Using Node.js HTTP adapter (required for gRPC)

import { createApp, createAdapter } from 'ramapi';
 
// Option 1: Via server config
const app1 = createApp({
  adapter: {
    type: 'uwebsockets',
    options: {
      idleTimeout: 120,
      maxBackpressure: 1024 * 1024,
    },
  },
});
 
// Option 2: Create adapter manually
const adapter = createAdapter('uwebsockets', {
  idleTimeout: 120,
});
 
// Option 3: Automatic selection
const app2 = createApp(); // Tries uWebSockets, falls back to Node.js
 
// Routes work the same regardless of adapter
app1.get('/users', async (ctx) => {
  ctx.json({ users: [] });
});
 
await app1.listen(3000);