peakroute 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+import * as node_tls from 'node:tls';
+import * as http from 'node:http';
+import * as net from 'node:net';
+
+/** Route info used by the proxy server to map hostnames to ports. */
+interface RouteInfo {
+    hostname: string;
+    port: number;
+}
+interface ProxyServerOptions {
+    /** Called on each request to get the current route table. */
+    getRoutes: () => RouteInfo[];
+    /** The port the proxy is listening on (used to build correct URLs). */
+    proxyPort: number;
+    /** Optional error logger; defaults to console.error. */
+    onError?: (message: string) => void;
+    /** When provided, enables HTTP/2 over TLS (HTTPS). */
+    tls?: {
+        cert: Buffer;
+        key: Buffer;
+        /** SNI callback for per-hostname certificate selection. */
+        SNICallback?: (servername: string, cb: (err: Error | null, ctx?: node_tls.SecureContext) => void) => void;
+    };
+}
+
+/** Response header used to identify a peakroute proxy (for health checks). */
+declare const PEAKROUTE_HEADER = "X-Peakroute";
+/** Server type returned by createProxyServer (plain HTTP/1.1 or net.Server TLS wrapper). */
+type ProxyServer = http.Server | net.Server;
+/**
+ * Create an HTTP proxy server that routes requests based on the Host header.
+ *
+ * Uses Node's built-in http module for proxying (no external dependencies).
+ * The `getRoutes` callback is invoked on every request so callers can provide
+ * either a static list or a live-updating one.
+ *
+ * When `tls` is provided, creates an HTTP/2 secure server with HTTP/1.1
+ * fallback (`allowHTTP1: true`). This enables HTTP/2 multiplexing for
+ * browsers while keeping WebSocket upgrades working over HTTP/1.1.
+ */
+declare function createProxyServer(options: ProxyServerOptions): ProxyServer;
+
+/** File permission mode for route and state files. */
+declare const FILE_MODE = 420;
+/** Directory permission mode for the user state directory. */
+declare const DIR_MODE = 493;
+/** Directory permission mode for the system state directory (world-writable with sticky bit). */
+declare const SYSTEM_DIR_MODE = 1023;
+/** File permission mode for shared state files in the system state directory. */
+declare const SYSTEM_FILE_MODE = 438;
+interface RouteMapping extends RouteInfo {
+    pid: number;
+}
+/**
+ * Thrown when a route is already registered by a live process and --force
+ * was not specified.
+ */
+declare class RouteConflictError extends Error {
+    readonly hostname: string;
+    readonly existingPid: number;
+    constructor(hostname: string, existingPid: number);
+}
+/**
+ * Manages route mappings stored as a JSON file on disk.
+ * Supports file locking and stale-route cleanup.
+ */
+declare class RouteStore {
+    /** The state directory path. */
+    readonly dir: string;
+    private readonly routesPath;
+    private readonly lockPath;
+    readonly pidPath: string;
+    readonly portFilePath: string;
+    private readonly onWarning;
+    constructor(dir: string, options?: {
+        onWarning?: (message: string) => void;
+    });
+    private isSystemDir;
+    private get dirMode();
+    private get fileMode();
+    ensureDir(): void;
+    getRoutesPath(): string;
+    private static readonly sleepBuffer;
+    private syncSleep;
+    private acquireLock;
+    private releaseLock;
+    private isProcessAlive;
+    /**
+     * Load routes from disk, filtering out stale entries whose owning process
+     * is no longer alive. Stale-route cleanup is only persisted when the caller
+     * already holds the lock (i.e. inside addRoute/removeRoute) to avoid
+     * unprotected concurrent writes.
+     */
+    loadRoutes(persistCleanup?: boolean): RouteMapping[];
+    private saveRoutes;
+    addRoute(hostname: string, port: number, pid: number, force?: boolean): void;
+    removeRoute(hostname: string): void;
+}
+
+/**
+ * Wrapper seguro para chmod que é no-op no Windows.
+ * PR #50 pattern: evita condicionais espalhadas pelo código.
+ */
+declare function chmodSafe(path: string, mode: number): void;
+/**
+ * Async version of chmodSafe.
+ */
+declare function chmodSafeAsync(path: string, mode: number): Promise<void>;
+/**
+ * When running under sudo, fix file ownership so the real user can
+ * read/write the file later without sudo. No-op when not running as root.
+ * On Windows, this is a no-op since there's no concept of uid/gid.
+ */
+declare function fixOwnership(...paths: string[]): void;
+/** Type guard for Node.js system errors with an error code. */
+declare function isErrnoException(err: unknown): err is NodeJS.ErrnoException;
+/**
+ * Escape HTML special characters to prevent XSS.
+ */
+declare function escapeHtml(str: string): string;
+/**
+ * Format a .localhost URL. Omits the port when it matches the protocol default
+ * (80 for HTTP, 443 for HTTPS).
+ */
+declare function formatUrl(hostname: string, proxyPort: number, tls?: boolean): string;
+/**
+ * Parse and normalize a hostname input for use as a .localhost subdomain.
+ * Strips protocol prefixes, validates characters, and appends .localhost if needed.
+ */
+declare function parseHostname(input: string): string;
+
+export { DIR_MODE, FILE_MODE, PEAKROUTE_HEADER, type ProxyServer, type ProxyServerOptions, RouteConflictError, type RouteInfo, type RouteMapping, RouteStore, SYSTEM_DIR_MODE, SYSTEM_FILE_MODE, chmodSafe, chmodSafeAsync, createProxyServer, escapeHtml, fixOwnership, formatUrl, isErrnoException, parseHostname };

package/dist/index.js

@@ -0,0 +1,34 @@
+import {
+  DIR_MODE,
+  FILE_MODE,
+  PEAKROUTE_HEADER,
+  RouteConflictError,
+  RouteStore,
+  SYSTEM_DIR_MODE,
+  SYSTEM_FILE_MODE,
+  chmodSafe,
+  chmodSafeAsync,
+  createProxyServer,
+  escapeHtml,
+  fixOwnership,
+  formatUrl,
+  isErrnoException,
+  parseHostname
+} from "./chunk-OWNUHDR5.js";
+export {
+  DIR_MODE,
+  FILE_MODE,
+  PEAKROUTE_HEADER,
+  RouteConflictError,
+  RouteStore,
+  SYSTEM_DIR_MODE,
+  SYSTEM_FILE_MODE,
+  chmodSafe,
+  chmodSafeAsync,
+  createProxyServer,
+  escapeHtml,
+  fixOwnership,
+  formatUrl,
+  isErrnoException,
+  parseHostname
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "peakroute",
+  "version": "0.5.0",
+  "description": "Replace port numbers with stable, named .localhost URLs. For humans and agents. (Formerly portless)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "peakroute": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "prepublishOnly": "bun run build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "echo 'No e2e tests defined yet'",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "local",
+    "development",
+    "proxy",
+    "localhost"
+  ],
+  "author": "Fala Dev",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/faladev/peakroute.git"
+  },
+  "homepage": "https://github.com/faladev/peakroute#readme",
+  "bugs": {
+    "url": "https://github.com/faladev/peakroute/issues"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.2",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  }
+}