@gjsify/http 0.0.4 → 0.1.0

package/src/index.ts

@@ -1,31 +1,175 @@
+// Node.js http module for GJS
+// Server: Soup.Server, Client: Soup.Session
+// Reference: Node.js lib/http.js
+
+export { STATUS_CODES, METHODS } from './constants.js';
+export { IncomingMessage } from './incoming-message.js';
+export { OutgoingMessage, Server, ServerResponse } from './server.js';
+export { ClientRequest } from './client-request.js';
+import { IncomingMessage } from './incoming-message.js';
+import { OutgoingMessage, Server, ServerResponse } from './server.js';
+import { ClientRequest } from './client-request.js';
+import type { ClientRequestOptions } from './client-request.js';
+import { URL } from 'node:url';
+
 /**
  * Performs the low-level validations on the provided `name` that are done when `res.setHeader(name, value)` is called.
- * Passing illegal value as `name` will result in a `TypeError` being thrown, identified by `code: 'ERR_INVALID_HTTP_TOKEN'`.
- * It is not necessary to use this method before passing headers to an HTTP request or response. The HTTP module will automatically validate such headers.
- * @param name
  * @since v14.3.0
  */
 export function validateHeaderName(name: string) {
-    if (!/^[\^`\-\w!#$%&'*+.|~]+$/.test(name)) {
-        const error = new TypeError(`Header name must be a valid HTTP token ["${name}"]`);
-        Object.defineProperty(error, 'code', { value: 'ERR_INVALID_HTTP_TOKEN' });
-        throw error;
-    }
+  if (typeof name !== 'string' || !/^[\^`\-\w!#$%&'*+.|~]+$/.test(name)) {
+    const error = new TypeError(`Header name must be a valid HTTP token ["${name}"]`);
+    Object.defineProperty(error, 'code', { value: 'ERR_INVALID_HTTP_TOKEN' });
+    throw error;
+  }
 }
 
 /**
  * Performs the low-level validations on the provided `value` that are done when `res.setHeader(name, value)` is called.
- * Passing illegal value as `value` will result in a `TypeError` being thrown.
- *  * Undefined value error is identified by `code: 'ERR_HTTP_INVALID_HEADER_VALUE'`.
- *  * Invalid value character error is identified by `code: 'ERR_INVALID_CHAR'`.
- * It is not necessary to use this method before passing headers to an HTTP request or response. The HTTP module will automatically validate such headers.
- * @param name 
- * @param value 
  */
 export function validateHeaderValue(name: string, value: any) {
-    if (/[^\t\u0020-\u007E\u0080-\u00FF]/.test(value)) {
-        const error = new TypeError(`Invalid character in header content ["${name}"]`);
-        Object.defineProperty(error, 'code', {value: 'ERR_INVALID_CHAR'});
-        throw error;
-    }
-}
+  if (value === undefined) {
+    const error = new TypeError(`Header "${name}" value must not be undefined`);
+    Object.defineProperty(error, 'code', { value: 'ERR_HTTP_INVALID_HEADER_VALUE' });
+    throw error;
+  }
+  if (typeof value === 'string' && /[^\t\u0020-\u007E\u0080-\u00FF]/.test(value)) {
+    const error = new TypeError(`Invalid character in header content ["${name}"]`);
+    Object.defineProperty(error, 'code', { value: 'ERR_INVALID_CHAR' });
+    throw error;
+  }
+}
+
+export interface AgentOptions {
+  keepAlive?: boolean;
+  keepAliveMsecs?: number;
+  maxSockets?: number;
+  maxTotalSockets?: number;
+  maxFreeSockets?: number;
+  timeout?: number;
+  scheduling?: 'fifo' | 'lifo';
+}
+
+/**
+ * Agent class for connection pooling.
+ * Soup.Session handles actual TCP connection pooling internally.
+ * This class provides the Node.js-compatible API surface for frameworks.
+ */
+export class Agent {
+  defaultPort = 80;
+  protocol = 'http:';
+  maxSockets: number;
+  maxTotalSockets: number;
+  maxFreeSockets: number;
+  keepAliveMsecs: number;
+  keepAlive: boolean;
+  scheduling: 'fifo' | 'lifo';
+
+  /** Pending requests per host (compatibility — Soup manages internally). */
+  readonly requests: Record<string, unknown[]> = {};
+  /** Active sockets per host (compatibility — Soup manages internally). */
+  readonly sockets: Record<string, unknown[]> = {};
+  /** Idle sockets per host (compatibility — Soup manages internally). */
+  readonly freeSockets: Record<string, unknown[]> = {};
+
+  constructor(options?: AgentOptions) {
+    this.keepAlive = options?.keepAlive ?? false;
+    this.keepAliveMsecs = options?.keepAliveMsecs ?? 1000;
+    this.maxSockets = options?.maxSockets ?? Infinity;
+    this.maxTotalSockets = options?.maxTotalSockets ?? Infinity;
+    this.maxFreeSockets = options?.maxFreeSockets ?? 256;
+    this.scheduling = options?.scheduling ?? 'lifo';
+  }
+
+  /** Destroy the agent and close idle connections. */
+  destroy(): void {
+    // Soup.Session handles cleanup on GC.
+  }
+
+  /** Return a connection pool key for the given options. */
+  getName(options: { host?: string; port?: number; localAddress?: string; family?: number }): string {
+    let name = options.host || 'localhost';
+    if (options.port) name += ':' + options.port;
+    if (options.localAddress) name += ':' + options.localAddress;
+    if (options.family === 4 || options.family === 6) name += ':' + options.family;
+    return name;
+  }
+}
+
+export const globalAgent = new Agent();
+
+/**
+ * Create an HTTP server.
+ */
+export function createServer(options?: Record<string, unknown> | ((req: IncomingMessage, res: ServerResponse) => void), requestListener?: (req: IncomingMessage, res: ServerResponse) => void): Server {
+  if (typeof options === 'function') {
+    return new Server(options);
+  }
+  return new Server(requestListener);
+}
+
+/**
+ * Make an HTTP request.
+ *
+ * @param url URL string, URL object, or request options
+ * @param options Request options (if url is string/URL)
+ * @param callback Response callback
+ */
+export function request(url: string | URL | ClientRequestOptions, options?: ClientRequestOptions | ((res: IncomingMessage) => void), callback?: (res: IncomingMessage) => void): ClientRequest {
+  return new ClientRequest(url, options, callback);
+}
+
+/**
+ * Make an HTTP GET request (convenience wrapper that calls req.end() automatically).
+ */
+export function get(url: string | URL | ClientRequestOptions, options?: ClientRequestOptions | ((res: IncomingMessage) => void), callback?: (res: IncomingMessage) => void): ClientRequest {
+  // Normalize arguments
+  let opts: ClientRequestOptions;
+  let cb: ((res: IncomingMessage) => void) | undefined = callback;
+
+  if (typeof url === 'string' || url instanceof URL) {
+    opts = typeof options === 'object' ? { ...options, method: 'GET' } : { method: 'GET' };
+    if (typeof options === 'function') cb = options;
+  } else {
+    opts = { ...url, method: 'GET' };
+    if (typeof options === 'function') cb = options;
+    url = opts as ClientRequestOptions;
+  }
+
+  const req = typeof url === 'string' || url instanceof URL
+    ? new ClientRequest(url, { ...opts, method: 'GET' }, cb)
+    : new ClientRequest({ ...opts, method: 'GET' }, cb);
+  req.end();
+  return req;
+}
+
+/** Max header size in bytes. */
+export const maxHeaderSize = 16384;
+
+/**
+ * Set the maximum number of idle HTTP parsers. Soup.Session handles
+ * connection pooling internally, so this is a no-op for compatibility.
+ * @since v18.8.0
+ */
+export function setMaxIdleHTTPParsers(_max: number): void {}
+
+import { STATUS_CODES as _STATUS_CODES, METHODS as _METHODS } from './constants.js';
+
+export default {
+  STATUS_CODES: _STATUS_CODES,
+  METHODS: _METHODS,
+  Server,
+  IncomingMessage,
+  OutgoingMessage,
+  ServerResponse,
+  ClientRequest,
+  Agent,
+  globalAgent,
+  createServer,
+  request,
+  get,
+  validateHeaderName,
+  validateHeaderValue,
+  maxHeaderSize,
+  setMaxIdleHTTPParsers,
+};

package/src/server.ts

@@ -0,0 +1,489 @@
+// Reference: Node.js lib/_http_server.js
+// Reimplemented for GJS using Soup.Server
+
+import Soup from '@girs/soup-3.0';
+import Gio from '@girs/gio-2.0';
+import { EventEmitter } from 'node:events';
+import { Writable } from 'node:stream';
+import { Buffer } from 'node:buffer';
+import { Socket as NetSocket } from '@gjsify/net/socket';
+import { deferEmit, ensureMainLoop } from '@gjsify/utils';
+import { STATUS_CODES } from './constants.js';
+import { IncomingMessage } from './incoming-message.js';
+
+/**
+ * OutgoingMessage — Base class for ServerResponse and ClientRequest.
+ * Reference: Node.js lib/_http_outgoing.js
+ */
+export class OutgoingMessage extends Writable {
+  headersSent = false;
+  sendDate = true;
+  finished = false;
+  socket: import('net').Socket | null = null;
+
+  protected _headers: Map<string, string | string[]> = new Map();
+
+  /** Set a header. */
+  setHeader(name: string, value: string | number | string[]): this {
+    this._headers.set(name.toLowerCase(), typeof value === 'number' ? String(value) : value);
+    return this;
+  }
+
+  /** Get a header. */
+  getHeader(name: string): string | string[] | undefined {
+    return this._headers.get(name.toLowerCase());
+  }
+
+  /** Remove a header. */
+  removeHeader(name: string): void {
+    this._headers.delete(name.toLowerCase());
+  }
+
+  /** Check if a header has been set. */
+  hasHeader(name: string): boolean {
+    return this._headers.has(name.toLowerCase());
+  }
+
+  /** Get all header names. */
+  getHeaderNames(): string[] {
+    return Array.from(this._headers.keys());
+  }
+
+  /** Get all headers as an object. */
+  getHeaders(): Record<string, string | string[]> {
+    const result: Record<string, string | string[]> = {};
+    for (const [key, value] of this._headers) {
+      result[key] = value;
+    }
+    return result;
+  }
+
+  /** Append a header value instead of replacing. */
+  appendHeader(name: string, value: string | string[]): this {
+    const lower = name.toLowerCase();
+    const existing = this._headers.get(lower);
+    if (existing === undefined) {
+      this._headers.set(lower, value);
+    } else if (Array.isArray(existing)) {
+      if (Array.isArray(value)) {
+        existing.push(...value);
+      } else {
+        existing.push(value);
+      }
+    } else {
+      if (Array.isArray(value)) {
+        this._headers.set(lower, [existing as string, ...value]);
+      } else {
+        this._headers.set(lower, [existing as string, value]);
+      }
+    }
+    return this;
+  }
+
+  /** Flush headers (no-op in base class). */
+  flushHeaders(): void {
+    this.headersSent = true;
+  }
+
+  _write(_chunk: any, _encoding: string, callback: (error?: Error | null) => void): void {
+    callback();
+  }
+}
+
+/**
+ * ServerResponse — Writable stream representing an HTTP response.
+ * Extends OutgoingMessage for shared header management.
+ */
+export class ServerResponse extends OutgoingMessage {
+  statusCode = 200;
+  statusMessage = '';
+
+  private _streaming = false;
+  private _soupMsg: Soup.ServerMessage;
+  private _timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(soupMsg: Soup.ServerMessage) {
+    super();
+    this._soupMsg = soupMsg;
+  }
+
+  /** Set a timeout for the response. Emits 'timeout' if response not sent within msecs. */
+  setTimeout(msecs: number, callback?: () => void): this {
+    if (this._timeoutTimer) {
+      clearTimeout(this._timeoutTimer);
+      this._timeoutTimer = null;
+    }
+    if (callback) this.once('timeout', callback);
+    if (msecs > 0) {
+      this._timeoutTimer = setTimeout(() => {
+        this._timeoutTimer = null;
+        this.emit('timeout');
+      }, msecs);
+    }
+    return this;
+  }
+
+  /** Write the status line and headers. */
+  writeHead(statusCode: number, statusMessage?: string | Record<string, string | string[]>, headers?: Record<string, string | string[]>): this {
+    this.statusCode = statusCode;
+
+    if (typeof statusMessage === 'object') {
+      headers = statusMessage;
+      statusMessage = undefined;
+    }
+
+    this.statusMessage = (statusMessage as string) || STATUS_CODES[statusCode] || '';
+
+    if (headers) {
+      for (const [key, value] of Object.entries(headers)) {
+        this.setHeader(key, value);
+      }
+    }
+
+    return this;
+  }
+
+  /** Send a 100 Continue response. */
+  writeContinue(callback?: () => void): void {
+    // Soup.Server handles 100-Continue automatically, but we track the call
+    if (callback) Promise.resolve().then(callback);
+  }
+
+  /** Send a 102 Processing response (WebDAV). */
+  writeProcessing(callback?: () => void): void {
+    if (callback) Promise.resolve().then(callback);
+  }
+
+  /** Flush headers (send them immediately). */
+  flushHeaders(): void {
+    // In our Soup-based implementation, headers are sent with the body.
+    // This is a no-op but marks headersSent for compatibility.
+    if (!this.headersSent) {
+      this.headersSent = true;
+    }
+  }
+
+  /** Add trailing headers for chunked transfer encoding. */
+  addTrailers(headers: Record<string, string>): void {
+    // Soup.Server doesn't support HTTP trailers natively.
+    // Store for compatibility but they won't be sent.
+    for (const [key, value] of Object.entries(headers)) {
+      // Trailers are appended after the body in chunked encoding
+      this._headers.set('trailer-' + key.toLowerCase(), value);
+    }
+  }
+
+  /**
+   * Send status + headers to the client via Soup and switch to streaming (chunked) mode.
+   * Called on the first write() — subsequent writes append chunks and unpause.
+   */
+  private _startStreaming(): void {
+    if (this._streaming) return;
+    this._streaming = true;
+    this.headersSent = true;
+
+    if (this._timeoutTimer) {
+      clearTimeout(this._timeoutTimer);
+      this._timeoutTimer = null;
+    }
+
+    this._soupMsg.set_status(this.statusCode, this.statusMessage || null);
+
+    const responseHeaders = this._soupMsg.get_response_headers();
+    responseHeaders.set_encoding(Soup.Encoding.CHUNKED);
+
+    if (!this._headers.has('connection')) {
+      responseHeaders.replace('Connection', 'close');
+    }
+
+    for (const [key, value] of this._headers) {
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          responseHeaders.append(key, v);
+        }
+      } else {
+        responseHeaders.replace(key, value as string);
+      }
+    }
+  }
+
+  /** Writable stream _write — sends headers on first call, then appends + flushes each chunk. */
+  _write(chunk: any, encoding: string, callback: (error?: Error | null) => void): void {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding as BufferEncoding);
+    this._startStreaming();
+    const responseBody = this._soupMsg.get_response_body();
+    // GJS overload: append(data: Uint8Array) — single argument, no MemoryUse parameter
+    responseBody.append(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
+    this._soupMsg.unpause();
+    callback();
+  }
+
+  /** Called by Writable.end() — completes the body (streaming) or sends batch response (no-body). */
+  _final(callback: (error?: Error | null) => void): void {
+    if (this._streaming) {
+      // Streaming mode — signal no more chunks
+      const responseBody = this._soupMsg.get_response_body();
+      responseBody.complete();
+      this._soupMsg.unpause();
+    } else {
+      // Batch mode — no write() was called (e.g. redirects, 204, empty end())
+      this._sendBatchResponse();
+    }
+    this.finished = true;
+    callback();
+  }
+
+  /** Batch response — sends status + headers + empty/no body in one shot (for responses without write()). */
+  private _sendBatchResponse(): void {
+    if (this.headersSent) return;
+    this.headersSent = true;
+
+    if (this._timeoutTimer) {
+      clearTimeout(this._timeoutTimer);
+      this._timeoutTimer = null;
+    }
+
+    this._soupMsg.set_status(this.statusCode, this.statusMessage || null);
+
+    const responseHeaders = this._soupMsg.get_response_headers();
+
+    if (!this._headers.has('connection')) {
+      responseHeaders.replace('Connection', 'close');
+    }
+
+    for (const [key, value] of this._headers) {
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          responseHeaders.append(key, v);
+        }
+      } else {
+        responseHeaders.replace(key, value as string);
+      }
+    }
+
+    // Empty body — use set_response so Soup knows the response is complete.
+    const contentType = (this._headers.get('content-type') as string) || 'text/plain';
+    this._soupMsg.set_response(contentType, Soup.MemoryUse.COPY, new Uint8Array(0));
+  }
+
+  /** Write status + headers + body in one call (convenience). */
+  end(chunk?: unknown, encoding?: BufferEncoding | (() => void), callback?: () => void): this {
+    if (typeof chunk === 'function') {
+      callback = chunk as () => void;
+      chunk = undefined;
+    } else if (typeof encoding === 'function') {
+      callback = encoding;
+      encoding = undefined;
+    }
+
+    if (chunk != null) {
+      this.write(chunk as string | Buffer, encoding as BufferEncoding);
+    }
+
+    super.end(callback);
+    return this;
+  }
+}
+
+// GC guard — GJS garbage-collects objects with no JS references. When frameworks
+// like Koa/Express create an http.Server inside .listen() and the caller discards
+// the return value, the Server (and its Soup.Server) gets collected after ~10s.
+// This Set keeps a strong reference to every listening server.
+const _activeServers = new Set<Server>();
+
+/**
+ * HTTP Server wrapping Soup.Server.
+ */
+export class Server extends EventEmitter {
+  listening = false;
+  maxHeadersCount = 2000;
+  timeout = 0;
+  keepAliveTimeout = 5000;
+  headersTimeout = 60000;
+  requestTimeout = 300000;
+
+  private _soupServer: Soup.Server | null = null;
+  private _address: { port: number; family: string; address: string } | null = null;
+
+  constructor(requestListener?: ((req: IncomingMessage, res: ServerResponse) => void) | Record<string, unknown>);
+  constructor(options: Record<string, unknown>, requestListener?: (req: IncomingMessage, res: ServerResponse) => void);
+  constructor(
+    optionsOrListener?: ((req: IncomingMessage, res: ServerResponse) => void) | Record<string, unknown>,
+    requestListener?: (req: IncomingMessage, res: ServerResponse) => void,
+  ) {
+    super();
+    // Support Node.js signature: new Server(options, listener)
+    const listener = typeof optionsOrListener === 'function' ? optionsOrListener : requestListener;
+    if (listener) {
+      this.on('request', listener);
+    }
+  }
+
+  listen(port?: number, hostname?: string, backlog?: number, callback?: () => void): this;
+  listen(port?: number, hostname?: string, callback?: () => void): this;
+  listen(port?: number, callback?: () => void): this;
+  listen(...args: unknown[]): this {
+    let port = 0;
+    let hostname = '0.0.0.0';
+    let callback: (() => void) | undefined;
+
+    for (const arg of args) {
+      if (typeof arg === 'number') port = arg;
+      else if (typeof arg === 'string') hostname = arg;
+      else if (typeof arg === 'function') callback = arg as () => void;
+    }
+
+    if (callback) this.once('listening', callback);
+
+    try {
+      this._soupServer = new Soup.Server({});
+
+      // Add a catch-all handler
+      this._soupServer.add_handler(null, (server: Soup.Server, msg: Soup.ServerMessage, path: string) => {
+        this._handleRequest(msg, path);
+      });
+
+      this._soupServer.listen_local(port, Soup.ServerListenOptions.IPV4_ONLY);
+      ensureMainLoop();
+
+      // Get the actual port from listeners
+      const listeners = this._soupServer.get_listeners();
+      let actualPort = port;
+      if (listeners && listeners.length > 0) {
+        const addr = listeners[0].get_local_address() as Gio.InetSocketAddress;
+        if (addr && typeof addr.get_port === 'function') {
+          actualPort = addr.get_port();
+        }
+      }
+
+      this.listening = true;
+      this._address = { port: actualPort, family: 'IPv4', address: hostname };
+      _activeServers.add(this);
+
+      deferEmit(this, 'listening');
+    } catch (err: unknown) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      if (this.listenerCount('error') === 0) {
+        // No error listener — throw like Node.js does for unhandled EventEmitter errors
+        throw error;
+      }
+      deferEmit(this, 'error', error);
+    }
+
+    return this;
+  }
+
+  private _handleRequest(soupMsg: Soup.ServerMessage, path: string): void {
+    const req = new IncomingMessage();
+    const res = new ServerResponse(soupMsg);
+
+    // Populate request properties
+    req.method = soupMsg.get_method();
+    req.url = soupMsg.get_uri().get_path();
+    const query = soupMsg.get_uri().get_query();
+    if (query) req.url += '?' + query;
+    req.httpVersion = '1.1';
+
+    // Parse headers
+    const requestHeaders = soupMsg.get_request_headers();
+    requestHeaders.foreach((name: string, value: string) => {
+      const lower = name.toLowerCase();
+      req.rawHeaders.push(name, value);
+      if (lower in req.headers) {
+        const existing = req.headers[lower];
+        if (Array.isArray(existing)) {
+          existing.push(value);
+        } else {
+          req.headers[lower] = [existing as string, value];
+        }
+      } else {
+        req.headers[lower] = value;
+      }
+    });
+
+    // Check for HTTP upgrade request (WebSocket, etc.)
+    // Reference: Node.js lib/_http_server.js — emits 'upgrade' with (req, socket, head)
+    const connectionHeader = (req.headers['connection'] as string || '').toLowerCase();
+    const upgradeHeader = (req.headers['upgrade'] as string || '').toLowerCase();
+    if (connectionHeader.includes('upgrade') && upgradeHeader && this.listenerCount('upgrade') > 0) {
+      // Steal the raw TCP connection from Soup before it sends a response.
+      // This gives us a Gio.IOStream positioned after the parsed HTTP request.
+      let ioStream: Gio.IOStream | null = null;
+      try {
+        ioStream = soupMsg.steal_connection();
+      } catch (err) {
+        // steal_connection() may fail if Soup has already started processing
+        // the response or if the connection is in an unexpected state.
+      }
+      if (ioStream) {
+        const socket = new NetSocket();
+        socket._setupFromIOStream(ioStream);
+        // head: any data after HTTP headers — empty for upgrade requests
+        this.emit('upgrade', req, socket, Buffer.alloc(0));
+        return;
+      }
+    }
+
+    // Get request body
+    const body = soupMsg.get_request_body();
+    if (body && body.data && body.data.length > 0) {
+      req._pushBody(body.data);
+    } else {
+      req._pushBody(null);
+    }
+
+    // Pause Soup's processing — we'll set the response when ServerResponse.end() is called
+    soupMsg.pause();
+
+    res.on('finish', () => {
+      soupMsg.unpause();
+    });
+
+    this.emit('request', req, res);
+  }
+
+  address(): { port: number; family: string; address: string } | null {
+    return this._address;
+  }
+
+  /**
+   * Register a WebSocket handler on this server (GJS only).
+   * Delegates to Soup.Server.add_websocket_handler().
+   * @param path URL path to handle WebSocket upgrades (e.g., '/ws')
+   * @param callback Called for each new WebSocket connection with the Soup.WebsocketConnection
+   */
+  addWebSocketHandler(
+    path: string,
+    callback: (connection: unknown) => void,
+  ): void {
+    if (!this._soupServer) {
+      throw new Error('Server must be listening before adding WebSocket handlers. Call listen() first.');
+    }
+    this._soupServer.add_websocket_handler(
+      path, null, null,
+      (_srv: Soup.Server, _msg: Soup.ServerMessage, _path: string, connection: unknown) => {
+        callback(connection);
+      },
+    );
+  }
+
+  close(callback?: (err?: Error) => void): this {
+    if (callback) this.once('close', callback);
+
+    if (this._soupServer) {
+      this._soupServer.disconnect();
+      this._soupServer = null;
+    }
+
+    this.listening = false;
+    _activeServers.delete(this);
+    deferEmit(this, 'close');
+    return this;
+  }
+
+  setTimeout(msecs: number, callback?: () => void): this {
+    this.timeout = msecs;
+    if (callback) this.on('timeout', callback);
+    return this;
+  }
+}