clearcote 0.38.1 → 0.40.0

package/dist/docker.d.ts

@@ -0,0 +1,153 @@
+import { spawnSync } from "node:child_process";
+import type { Browser } from "playwright-core";
+export declare const DEFAULT_REPOSITORY = "teamflatearth/clearcote";
+export declare const TEST_ONLY_ASSUME_MACOS = "CLEARCOTE_TEST_ONLY_ASSUME_MACOS";
+export declare const SERVE_PROTOCOL = 2;
+/** launch() needs Docker on this host (macOS has no native Clearcote build) and it is missing or not running. */
+export declare class DockerUnavailableError extends Error {
+    constructor(message: string);
+}
+/** The Docker options of launch(). */
+export interface DockerOption {
+    /** Run Clearcote in its Docker image. Unset: on macOS only (there is no native macOS build), unless
+     * executablePath / CLEARCOTE_BINARY names a binary. false (or CLEARCOTE_DOCKER=0) turns it off;
+     * true uses the image on any OS. */
+    docker?: boolean;
+    /** The image to run. Default CLEARCOTE_DOCKER_IMAGE, else teamflatearth/clearcote:sdk-<SDK version>. */
+    dockerImage?: string;
+}
+export declare const DOCKER_ACCEPTED: readonly string[];
+export declare function hostIsMacos(): boolean;
+/** Whether this launch runs in the Clearcote Docker image (see the header). */
+export declare function dockerRequested(docker: unknown, options?: Record<string, unknown>): boolean;
+export declare function defaultImage(): string;
+/** The CC_* (and licence) variables the image is started with. Throws naming the first option the
+ * image cannot take. */
+export declare function containerEnv(options: Record<string, unknown>): Record<string, string>;
+export interface CliResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** A starting container's log, kept in memory (it is created with --rm: once stopped, its log is gone). The
+ * lines saying what the entrypoint applied (serve-state, engine, proxy) are kept apart in `marks`, whatever
+ * Chrome logs after them. */
+export interface LogTail {
+    text(waitMs?: number): Promise<string>;
+    waitMarks(pattern: RegExp, waitMs?: number): Promise<string[]>;
+    stop(): void;
+}
+declare function followLogs(exe: string, id: string): LogTail;
+/** The docker CLI. Seams: tests replace `which`, `run` and `followLogs`. */
+export declare const dockerCli: {
+    which: () => string | null;
+    run: (argv: string[], env?: Record<string, string>, timeoutMs?: number, input?: Buffer) => Promise<CliResult>;
+    followLogs: typeof followLogs;
+};
+/** The docker executable, or DockerUnavailableError saying what to do. */
+export declare function checkDocker(): Promise<string>;
+/** How long a launched container waits with no CDP client before it stops itself: CLEARCOTE_DOCKER_IDLE_EXIT
+ * (seconds, 0 = never), default 30. */
+export declare function idleExitSeconds(): number;
+/** The named volume a licensed container keeps its engine in (shared, so it downloads once):
+ * CLEARCOTE_DOCKER_CACHE_VOLUME, default clearcote-cache. */
+export declare function cacheVolume(): string;
+export declare function pidAlive(pid: number): boolean;
+/** What this host says about processes: /proc where there is one, `ps` elsewhere. Seams: tests replace members. */
+export declare const hostProbe: {
+    platform: () => string;
+    readText: (path: string) => string | null;
+    bootId: () => string | null;
+    pidNamespace: () => string | null;
+    spawnSync: typeof spawnSync;
+};
+/** `ps -o lstart=` prints local time, in the locale's words. Pinned, so an owner and a sweeper that run with
+ * different TZ / LANG settings (or one script that changes TZ between launches) read the same string for the
+ * same process. Without it a sweeper in another time zone took a live owner for a reused pid. */
+export declare const PS_ENV: {
+    readonly TZ: "UTC0";
+    readonly LC_ALL: "C";
+};
+/** A marker that differs once `pid` belongs to another process (it was reused), or null when it cannot be
+ * read here. Linux: the start time from /proc; macOS: `ps -o lstart=` in UTC and the C locale; Windows: not
+ * readable from Node (null: the pid alone is then trusted, which only ever keeps a container). The same
+ * strings in all three SDKs. */
+export declare function processStart(pid: number): string | null;
+/** This process's owner token, recording it (once) under ~/.clearcote/docker-owners/. */
+export declare function ownerToken(): string;
+/** Forget this process's token (tests: a new HOME gets a new record). */
+export declare function resetOwnerToken(): void;
+type OwnerRecord = {
+    pid?: unknown;
+    start?: string | null;
+    pidns?: string | null;
+    boot?: string | null;
+    host?: unknown;
+};
+/** The fields an owner record from this process would carry besides its pid and start marker. */
+export declare const ownerHere: () => {
+    host: string;
+    boot: string | null;
+    pidns: string | null;
+};
+/** true or false for the owner a record describes, or null when that cannot be told for certain here: a record
+ * whose host, boot id or PID namespace is not exactly what this process would record (missing ones included),
+ * or whose pid is not a positive integer. A pid that is alive with a start marker of the same kind but another
+ * value was reused (false); one whose marker cannot be compared counts as alive. */
+export declare function ownerAlive(rec: OwnerRecord): boolean | null;
+/**
+ * Stop and remove containers an earlier launch left behind whose owner process is certainly gone (killed,
+ * crashed): their token's record is in this home, from this boot and PID namespace, and its process no longer
+ * exists. They would stop on their own after the idle period; this frees their licence seat now. Anything else
+ * -- live owners, owners in another namespace or on another machine, containers without a token -- is left
+ * alone. Resolves to the ids removed.
+ */
+export declare function sweepStale(exe: string): Promise<string[]>;
+/** The serve protocol `image` speaks (its PROTOCOL_LABEL; 0 for an image without it), pulling the image first
+ * when it is not here. Known before a container exists, so the settings a container gets are always ones its
+ * entrypoint understands. */
+export declare function imageProtocol(exe: string, image: string, quiet?: boolean): Promise<number>;
+/** Why an image older than FIRST_PROTOCOL_TAG cannot take this proxy, or null. Its entrypoint drops the password
+ * of an http(s) proxy (Chrome is then challenged and nothing answers: every request fails), and hands a SOCKS5
+ * password to an engine switch only the licensed engine has -- as written in the URL, without decoding it, so a
+ * username or password with characters that have to be escaped there arrives wrong. */
+export declare function legacyProxyRefusal(image: string, proxyUrlValue: string | null | undefined, licensed: boolean): string | null;
+/** What the container did not apply that was asked for (empty when all is well), from the lines its
+ * entrypoint logged: serve-state (protocol 2) or, for an older image, its engine and proxy lines. */
+export declare function verifyApplied(marks: string[], protocol: number, expect: {
+    licensed: boolean;
+    proxy?: string | null;
+}): string[];
+/** A ustar archive of one file, as `docker cp -` reads it. */
+export declare function tarOneFile(name: string, data: Buffer, opts: {
+    uid: number;
+    gid: number;
+    mode: number;
+}): Buffer;
+export interface DockerContainer {
+    id: string;
+    image: string;
+    endpoint: string;
+    serveProtocol: number;
+}
+/**
+ * Start the image and wait for its CDP endpoint. Nothing is left running when this rejects.
+ *
+ * What the image does with its settings is known first (imageProtocol). An image of this SDK's protocol gets
+ * --rm, an idle exit (it stops once no CDP client has been connected for idleExitSeconds(), counted from when
+ * its CDP answers) and the licence key and proxy URL as a file copied in, not as -e variables `docker inspect`
+ * would show. An older image gets plain variables -- they still work -- and a warning that they are visible
+ * and that it will not stop on its own -- and is refused, before it starts, a proxy password it cannot answer
+ * (legacyProxyRefusal). Either way, once the browser answers, the container's own log must show the licensed
+ * engine when a key was given and the proxy when one was given, logged in to when it needs a password
+ * (verifyApplied); otherwise it is stopped and removed and launch() rejects: a browser on the open engine, one
+ * sending traffic direct, or one whose every request the proxy turns away is never handed back in their place. The container carries this process's owner token for sweepStale().
+ */
+export declare function startContainer(options: Record<string, unknown>): Promise<DockerContainer & {
+    exe: string;
+}>;
+/** `launch()` on macOS (see the header): the Playwright Browser of a Clearcote container, which also
+ * carries `dockerContainer` ({ id, image, endpoint }). close() disconnects and stops the container. */
+export declare function launchDocker(options: Record<string, unknown>): Promise<Browser>;
+export {};
+//# sourceMappingURL=docker.d.ts.map

package/dist/docker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker.d.ts","sourceRoot":"","sources":["../src/docker.ts"],"names":[],"mappings":"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"}