@stacksjs/rpx/dist/hosts.d.ts

A modern and smart reverse proxy.

/** `.localhost` names resolve to loopback per RFC 6761 — no /etc/hosts entry needed. */
export declare function isLoopbackDevelopmentHost(host: string): boolean;
/**
 * Parse one /etc/hosts line into address, hostnames, and rpx ownership.
 * Returns null for blank lines and pure comments. Host matching anywhere in
 * this module is exact token comparison — never substring — so removing
 * `example.test` can never touch `api.example.test`.
 */
export declare function parseHostsLine(line: string): HostsLine | null;
/** True when the line maps `host` exactly (one of its names) to loopback. */
export declare function hostsLineMapsHost(line: string, host: string): boolean;
/**
 * Remove rpx-owned loopback lines for `hostsToRemove` from hosts-file content.
 *
 * Ownership rules:
 *   - Inline-marked lines (`# rpx:pid=N` / `# rpx`) are dropped when any of
 *     their exact hostnames is in the removal set.
 *   - Legacy `# Added by rpx` blocks own the address lines directly beneath
 *     them; matched lines are dropped and the comment is dropped only when
 *     its whole block went away (previously every legacy comment in the file
 *     was stripped even when its hosts stayed — orphaning unmarked lines).
 *   - Unmarked lines are never touched: a hand-written entry belongs to the
 *     user, and a missing marker must not become a deletion license.
 */
export declare function filterRpxHostsEntries(content: string, hostsToRemove: string[]): HostsFilterResult;
/**
 * Drop inline-marked lines whose owning PID is dead. Lines without a PID
 * stamp (legacy blocks, hand-written entries) are kept: without an owner to
 * probe there is no safe automatic removal signal.
 */
export declare function dropStaleRpxHostsLines(content: string, isAlive: (pid: number) => boolean): StaleRpxHostsResult;
export declare function addHosts(hosts: string[], verbose?: boolean): Promise<void>;
export declare function removeHosts(hosts: string[], verbose?: boolean): Promise<void>;
export declare function checkHosts(hosts: string[], verbose?: boolean): Promise<boolean[]>;
/**
 * Hostnames on inline-marked rpx lines whose owning PID is dead. Read-only:
 * safe for unprivileged diagnostics (e.g. `buddy doctor`) since /etc/hosts is
 * world-readable. Returns [] when the file cannot be read.
 */
export declare function findStaleRpxHosts(isAlive?: (pid: number) => boolean): Promise<string[]>;
/**
 * Remove inline-marked rpx hosts lines whose owning PID is dead. Runs inside
 * the (root) daemon's periodic GC so entries orphaned by a killed dev session
 * disappear within seconds instead of hijacking the domain forever. Returns
 * the removed hostnames; [] when nothing was stale or the write failed.
 */
export declare function removeStaleRpxHosts(opts?: { verbose?: boolean, isAlive?: (pid: number) => boolean }): Promise<string[]>;
export declare const hostsFilePath: string;
/**
 * Inline marker identifying an /etc/hosts line rpx owns. New entries are
 * stamped with the owning process id so a garbage-collection pass (the
 * daemon's periodic sweep, or `removeStaleRpxHosts`) can reap lines whose
 * owner died without cleaning up:
 *
 *   127.0.0.1 example.test # rpx:pid=12345
 *
 * Older entries used a `# Added by rpx` comment above each address pair;
 * removal still understands that legacy layout.
 */
export declare const RPX_HOSTS_MARKER: '# rpx';
export declare interface HostsLine {
  address: string
  names: string[]
  comment: string
  rpxPid: number | null
  rpxManaged: boolean
}
export declare interface HostsFilterResult {
  content: string
  removed: string[]
}
export declare interface StaleRpxHostsResult {
  content: string
  removed: string[]
  stalePids: number[]
}