@gjsify/http 0.0.3 → 0.1.0

package/lib/esm/server.js

@@ -0,0 +1,371 @@
+import Soup from "@girs/soup-3.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";
+class OutgoingMessage extends Writable {
+  headersSent = false;
+  sendDate = true;
+  finished = false;
+  socket = null;
+  _headers = /* @__PURE__ */ new Map();
+  /** Set a header. */
+  setHeader(name, value) {
+    this._headers.set(name.toLowerCase(), typeof value === "number" ? String(value) : value);
+    return this;
+  }
+  /** Get a header. */
+  getHeader(name) {
+    return this._headers.get(name.toLowerCase());
+  }
+  /** Remove a header. */
+  removeHeader(name) {
+    this._headers.delete(name.toLowerCase());
+  }
+  /** Check if a header has been set. */
+  hasHeader(name) {
+    return this._headers.has(name.toLowerCase());
+  }
+  /** Get all header names. */
+  getHeaderNames() {
+    return Array.from(this._headers.keys());
+  }
+  /** Get all headers as an object. */
+  getHeaders() {
+    const result = {};
+    for (const [key, value] of this._headers) {
+      result[key] = value;
+    }
+    return result;
+  }
+  /** Append a header value instead of replacing. */
+  appendHeader(name, value) {
+    const lower = name.toLowerCase();
+    const existing = this._headers.get(lower);
+    if (existing === void 0) {
+      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, ...value]);
+      } else {
+        this._headers.set(lower, [existing, value]);
+      }
+    }
+    return this;
+  }
+  /** Flush headers (no-op in base class). */
+  flushHeaders() {
+    this.headersSent = true;
+  }
+  _write(_chunk, _encoding, callback) {
+    callback();
+  }
+}
+class ServerResponse extends OutgoingMessage {
+  statusCode = 200;
+  statusMessage = "";
+  _streaming = false;
+  _soupMsg;
+  _timeoutTimer = null;
+  constructor(soupMsg) {
+    super();
+    this._soupMsg = soupMsg;
+  }
+  /** Set a timeout for the response. Emits 'timeout' if response not sent within msecs. */
+  setTimeout(msecs, callback) {
+    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, statusMessage, headers) {
+    this.statusCode = statusCode;
+    if (typeof statusMessage === "object") {
+      headers = statusMessage;
+      statusMessage = void 0;
+    }
+    this.statusMessage = statusMessage || 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) {
+    if (callback) Promise.resolve().then(callback);
+  }
+  /** Send a 102 Processing response (WebDAV). */
+  writeProcessing(callback) {
+    if (callback) Promise.resolve().then(callback);
+  }
+  /** Flush headers (send them immediately). */
+  flushHeaders() {
+    if (!this.headersSent) {
+      this.headersSent = true;
+    }
+  }
+  /** Add trailing headers for chunked transfer encoding. */
+  addTrailers(headers) {
+    for (const [key, value] of Object.entries(headers)) {
+      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.
+   */
+  _startStreaming() {
+    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);
+      }
+    }
+  }
+  /** Writable stream _write — sends headers on first call, then appends + flushes each chunk. */
+  _write(chunk, encoding, callback) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding);
+    this._startStreaming();
+    const responseBody = this._soupMsg.get_response_body();
+    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) {
+    if (this._streaming) {
+      const responseBody = this._soupMsg.get_response_body();
+      responseBody.complete();
+      this._soupMsg.unpause();
+    } else {
+      this._sendBatchResponse();
+    }
+    this.finished = true;
+    callback();
+  }
+  /** Batch response — sends status + headers + empty/no body in one shot (for responses without write()). */
+  _sendBatchResponse() {
+    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);
+      }
+    }
+    const contentType = this._headers.get("content-type") || "text/plain";
+    this._soupMsg.set_response(contentType, Soup.MemoryUse.COPY, new Uint8Array(0));
+  }
+  /** Write status + headers + body in one call (convenience). */
+  end(chunk, encoding, callback) {
+    if (typeof chunk === "function") {
+      callback = chunk;
+      chunk = void 0;
+    } else if (typeof encoding === "function") {
+      callback = encoding;
+      encoding = void 0;
+    }
+    if (chunk != null) {
+      this.write(chunk, encoding);
+    }
+    super.end(callback);
+    return this;
+  }
+}
+const _activeServers = /* @__PURE__ */ new Set();
+class Server extends EventEmitter {
+  listening = false;
+  maxHeadersCount = 2e3;
+  timeout = 0;
+  keepAliveTimeout = 5e3;
+  headersTimeout = 6e4;
+  requestTimeout = 3e5;
+  _soupServer = null;
+  _address = null;
+  constructor(optionsOrListener, requestListener) {
+    super();
+    const listener = typeof optionsOrListener === "function" ? optionsOrListener : requestListener;
+    if (listener) {
+      this.on("request", listener);
+    }
+  }
+  listen(...args) {
+    let port = 0;
+    let hostname = "0.0.0.0";
+    let callback;
+    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;
+    }
+    if (callback) this.once("listening", callback);
+    try {
+      this._soupServer = new Soup.Server({});
+      this._soupServer.add_handler(null, (server, msg, path) => {
+        this._handleRequest(msg, path);
+      });
+      this._soupServer.listen_local(port, Soup.ServerListenOptions.IPV4_ONLY);
+      ensureMainLoop();
+      const listeners = this._soupServer.get_listeners();
+      let actualPort = port;
+      if (listeners && listeners.length > 0) {
+        const addr = listeners[0].get_local_address();
+        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) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      if (this.listenerCount("error") === 0) {
+        throw error;
+      }
+      deferEmit(this, "error", error);
+    }
+    return this;
+  }
+  _handleRequest(soupMsg, path) {
+    const req = new IncomingMessage();
+    const res = new ServerResponse(soupMsg);
+    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";
+    const requestHeaders = soupMsg.get_request_headers();
+    requestHeaders.foreach((name, value) => {
+      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, value];
+        }
+      } else {
+        req.headers[lower] = value;
+      }
+    });
+    const connectionHeader = (req.headers["connection"] || "").toLowerCase();
+    const upgradeHeader = (req.headers["upgrade"] || "").toLowerCase();
+    if (connectionHeader.includes("upgrade") && upgradeHeader && this.listenerCount("upgrade") > 0) {
+      let ioStream = null;
+      try {
+        ioStream = soupMsg.steal_connection();
+      } catch (err) {
+      }
+      if (ioStream) {
+        const socket = new NetSocket();
+        socket._setupFromIOStream(ioStream);
+        this.emit("upgrade", req, socket, Buffer.alloc(0));
+        return;
+      }
+    }
+    const body = soupMsg.get_request_body();
+    if (body && body.data && body.data.length > 0) {
+      req._pushBody(body.data);
+    } else {
+      req._pushBody(null);
+    }
+    soupMsg.pause();
+    res.on("finish", () => {
+      soupMsg.unpause();
+    });
+    this.emit("request", req, res);
+  }
+  address() {
+    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, callback) {
+    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, _msg, _path, connection) => {
+        callback(connection);
+      }
+    );
+  }
+  close(callback) {
+    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, callback) {
+    this.timeout = msecs;
+    if (callback) this.on("timeout", callback);
+    return this;
+  }
+}
+export {
+  OutgoingMessage,
+  Server,
+  ServerResponse
+};

package/lib/types/client-request.d.ts

@@ -0,0 +1,65 @@
+import { URL } from 'node:url';
+import { OutgoingMessage } from './server.js';
+import { IncomingMessage } from './incoming-message.js';
+export interface ClientRequestOptions {
+    protocol?: string;
+    hostname?: string;
+    host?: string;
+    port?: number | string;
+    path?: string;
+    method?: string;
+    headers?: Record<string, string | number | string[]>;
+    timeout?: number;
+    agent?: any;
+    setHost?: boolean;
+    /** Basic authentication string in the format 'user:password'. */
+    auth?: string;
+    /** Local address to bind the request from. */
+    localAddress?: string;
+    /** IP address family (4 or 6). */
+    family?: 4 | 6 | 0;
+    /** Signal to abort the request. */
+    signal?: AbortSignal;
+}
+/**
+ * ClientRequest — Writable stream representing an outgoing HTTP request.
+ *
+ * Usage:
+ *   const req = http.request(options, (res) => { ... });
+ *   req.write(body);
+ *   req.end();
+ */
+export declare class ClientRequest extends OutgoingMessage {
+    method: string;
+    path: string;
+    protocol: string;
+    host: string;
+    hostname: string;
+    port: number;
+    aborted: boolean;
+    reusedSocket: boolean;
+    maxHeadersCount: number;
+    private _chunks;
+    private _session;
+    private _message;
+    private _cancellable;
+    private _timeout;
+    private _timeoutTimer;
+    private _responseCallback?;
+    constructor(url: string | URL | ClientRequestOptions, options?: ClientRequestOptions | ((res: IncomingMessage) => void), callback?: (res: IncomingMessage) => void);
+    private _buildUrl;
+    /** Get raw header names and values as a flat array. */
+    getRawHeaderNames(): string[];
+    /** Flush headers — marks headers as sent. */
+    flushHeaders(): void;
+    /** Set timeout for the request. Emits 'timeout' if no response within msecs. */
+    setTimeout(msecs: number, callback?: () => void): this;
+    /** Abort the request. */
+    abort(): void;
+    /** Writable stream _write implementation — collect body chunks. */
+    _write(chunk: any, encoding: string, callback: (error?: Error | null) => void): void;
+    /** Called when the writable stream ends — send the request. */
+    _final(callback: (error?: Error | null) => void): void;
+    private _applyHeaders;
+    private _sendRequest;
+}

package/lib/types/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const STATUS_CODES: Record<number, string>;
+export declare const METHODS: string[];

package/lib/types/incoming-message.d.ts

@@ -0,0 +1,25 @@
+import { Readable } from 'node:stream';
+/**
+ * IncomingMessage — Readable stream for HTTP request (server-side) or response (client-side).
+ */
+export declare class IncomingMessage extends Readable {
+    httpVersion: string;
+    httpVersionMajor: number;
+    httpVersionMinor: number;
+    headers: Record<string, string | string[]>;
+    rawHeaders: string[];
+    method?: string;
+    url?: string;
+    statusCode?: number;
+    statusMessage?: string;
+    complete: boolean;
+    socket: any;
+    aborted: boolean;
+    private _timeoutTimer;
+    constructor();
+    _read(_size: number): void;
+    /** Finish the readable stream with the body data (used by server-side handler). */
+    _pushBody(body: Uint8Array | null): void;
+    setTimeout(msecs: number, callback?: () => void): this;
+    destroy(error?: Error): this;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,102 @@
+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.
+ * @since v14.3.0
+ */
+export declare function validateHeaderName(name: string): void;
+/**
+ * Performs the low-level validations on the provided `value` that are done when `res.setHeader(name, value)` is called.
+ */
+export declare function validateHeaderValue(name: string, value: any): void;
+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 declare class Agent {
+    defaultPort: number;
+    protocol: string;
+    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);
+    /** Destroy the agent and close idle connections. */
+    destroy(): void;
+    /** Return a connection pool key for the given options. */
+    getName(options: {
+        host?: string;
+        port?: number;
+        localAddress?: string;
+        family?: number;
+    }): string;
+}
+export declare const globalAgent: Agent;
+/**
+ * Create an HTTP server.
+ */
+export declare function createServer(options?: Record<string, unknown> | ((req: IncomingMessage, res: ServerResponse) => void), requestListener?: (req: IncomingMessage, res: ServerResponse) => void): Server;
+/**
+ * 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 declare function request(url: string | URL | ClientRequestOptions, options?: ClientRequestOptions | ((res: IncomingMessage) => void), callback?: (res: IncomingMessage) => void): ClientRequest;
+/**
+ * Make an HTTP GET request (convenience wrapper that calls req.end() automatically).
+ */
+export declare function get(url: string | URL | ClientRequestOptions, options?: ClientRequestOptions | ((res: IncomingMessage) => void), callback?: (res: IncomingMessage) => void): ClientRequest;
+/** Max header size in bytes. */
+export declare 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 declare function setMaxIdleHTTPParsers(_max: number): void;
+declare const _default: {
+    STATUS_CODES: Record<number, string>;
+    METHODS: string[];
+    Server: typeof Server;
+    IncomingMessage: typeof IncomingMessage;
+    OutgoingMessage: typeof OutgoingMessage;
+    ServerResponse: typeof ServerResponse;
+    ClientRequest: typeof ClientRequest;
+    Agent: typeof Agent;
+    globalAgent: Agent;
+    createServer: typeof createServer;
+    request: typeof request;
+    get: typeof get;
+    validateHeaderName: typeof validateHeaderName;
+    validateHeaderValue: typeof validateHeaderValue;
+    maxHeaderSize: number;
+    setMaxIdleHTTPParsers: typeof setMaxIdleHTTPParsers;
+};
+export default _default;

package/lib/types/server.d.ts

@@ -0,0 +1,102 @@
+import Soup from '@girs/soup-3.0';
+import { EventEmitter } from 'node:events';
+import { Writable } from 'node:stream';
+import { IncomingMessage } from './incoming-message.js';
+/**
+ * OutgoingMessage — Base class for ServerResponse and ClientRequest.
+ * Reference: Node.js lib/_http_outgoing.js
+ */
+export declare class OutgoingMessage extends Writable {
+    headersSent: boolean;
+    sendDate: boolean;
+    finished: boolean;
+    socket: import('net').Socket | null;
+    protected _headers: Map<string, string | string[]>;
+    /** Set a header. */
+    setHeader(name: string, value: string | number | string[]): this;
+    /** Get a header. */
+    getHeader(name: string): string | string[] | undefined;
+    /** Remove a header. */
+    removeHeader(name: string): void;
+    /** Check if a header has been set. */
+    hasHeader(name: string): boolean;
+    /** Get all header names. */
+    getHeaderNames(): string[];
+    /** Get all headers as an object. */
+    getHeaders(): Record<string, string | string[]>;
+    /** Append a header value instead of replacing. */
+    appendHeader(name: string, value: string | string[]): this;
+    /** Flush headers (no-op in base class). */
+    flushHeaders(): void;
+    _write(_chunk: any, _encoding: string, callback: (error?: Error | null) => void): void;
+}
+/**
+ * ServerResponse — Writable stream representing an HTTP response.
+ * Extends OutgoingMessage for shared header management.
+ */
+export declare class ServerResponse extends OutgoingMessage {
+    statusCode: number;
+    statusMessage: string;
+    private _streaming;
+    private _soupMsg;
+    private _timeoutTimer;
+    constructor(soupMsg: Soup.ServerMessage);
+    /** Set a timeout for the response. Emits 'timeout' if response not sent within msecs. */
+    setTimeout(msecs: number, callback?: () => void): this;
+    /** Write the status line and headers. */
+    writeHead(statusCode: number, statusMessage?: string | Record<string, string | string[]>, headers?: Record<string, string | string[]>): this;
+    /** Send a 100 Continue response. */
+    writeContinue(callback?: () => void): void;
+    /** Send a 102 Processing response (WebDAV). */
+    writeProcessing(callback?: () => void): void;
+    /** Flush headers (send them immediately). */
+    flushHeaders(): void;
+    /** Add trailing headers for chunked transfer encoding. */
+    addTrailers(headers: Record<string, string>): void;
+    /**
+     * 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;
+    /** Writable stream _write — sends headers on first call, then appends + flushes each chunk. */
+    _write(chunk: any, encoding: string, callback: (error?: Error | null) => void): void;
+    /** Called by Writable.end() — completes the body (streaming) or sends batch response (no-body). */
+    _final(callback: (error?: Error | null) => void): void;
+    /** Batch response — sends status + headers + empty/no body in one shot (for responses without write()). */
+    private _sendBatchResponse;
+    /** Write status + headers + body in one call (convenience). */
+    end(chunk?: unknown, encoding?: BufferEncoding | (() => void), callback?: () => void): this;
+}
+/**
+ * HTTP Server wrapping Soup.Server.
+ */
+export declare class Server extends EventEmitter {
+    listening: boolean;
+    maxHeadersCount: number;
+    timeout: number;
+    keepAliveTimeout: number;
+    headersTimeout: number;
+    requestTimeout: number;
+    private _soupServer;
+    private _address;
+    constructor(requestListener?: ((req: IncomingMessage, res: ServerResponse) => void) | Record<string, unknown>);
+    constructor(options: Record<string, unknown>, requestListener?: (req: IncomingMessage, res: ServerResponse) => void);
+    listen(port?: number, hostname?: string, backlog?: number, callback?: () => void): this;
+    listen(port?: number, hostname?: string, callback?: () => void): this;
+    listen(port?: number, callback?: () => void): this;
+    private _handleRequest;
+    address(): {
+        port: number;
+        family: string;
+        address: string;
+    } | null;
+    /**
+     * 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;
+    close(callback?: (err?: Error) => void): this;
+    setTimeout(msecs: number, callback?: () => void): this;
+}