@slopware/sloppy-linux-x64 0.1.0-alpha.0

package/stdlib/sloppy/internal/shared.js

@@ -0,0 +1,32 @@
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+
+function createMutationGuard(subject) {
+    let frozen = false;
+
+    return Object.freeze({
+        assertMutable() {
+            if (frozen) {
+                throw new Error(`Sloppy ${subject} is frozen and cannot be modified.`);
+            }
+        },
+        freeze() {
+            frozen = true;
+        },
+        isFrozen() {
+            return frozen;
+        },
+    });
+}
+
+function isPromiseLike(value) {
+    return value !== null && typeof value === "object" && typeof value.then === "function";
+}
+
+export { createMutationGuard, isPlainObject, isPromiseLike };

package/stdlib/sloppy/internal/testhost-diagnostics.js

@@ -0,0 +1,88 @@
+import { redactObject, redactTextSecrets } from "./redaction.js";
+import { isPlainObject, requirePlainObject } from "./validation.js";
+
+function redactConfiguredSecrets(value, secretTexts) {
+    return redactTextSecrets(value, secretTexts);
+}
+
+function redactedValue(key, value, secretTexts = []) {
+    return redactObject({ [key]: value }, {
+        secrets: secretTexts,
+        redactText: (text) => redactConfiguredSecrets(text, secretTexts),
+        stringifyPrimitives: true,
+    })[key];
+}
+
+export function normalizeOverrideMap(value, subject) {
+    if (value === undefined) {
+        return Object.freeze({});
+    }
+    requirePlainObject(value, `Sloppy TestHost ${subject} overrides must be a plain object.`);
+    return Object.freeze({ ...value });
+}
+
+export function createDiagnosticsStore(secrets = []) {
+    const records = [];
+    const secretTexts = secrets
+        .filter((value) => typeof value === "string" && value.length > 0)
+        .map((value) => String(value));
+
+    function sanitizeRecord(record) {
+        const fields = {};
+        for (const [key, value] of Object.entries(record.fields ?? {})) {
+            fields[key] = redactedValue(key, value, secretTexts);
+        }
+        return Object.freeze({
+            code: String(record.code),
+            subsystem: record.subsystem ?? "testhost",
+            severity: record.severity ?? "info",
+            message: redactConfiguredSecrets(record.message ?? record.code, secretTexts),
+            fields: Object.freeze(fields),
+        });
+    }
+
+    const diagnostics = {
+        record(record) {
+            records.push(sanitizeRecord(record));
+        },
+        snapshot() {
+            return Object.freeze([...records]);
+        },
+        latest() {
+            return records.at(-1);
+        },
+        filter(criteria = {}) {
+            if (!isPlainObject(criteria)) {
+                throw new TypeError("Sloppy TestHost diagnostics filter criteria must be a plain object.");
+            }
+            return Object.freeze(records.filter((record) => {
+                if (criteria.code !== undefined && record.code !== criteria.code) {
+                    return false;
+                }
+                if (criteria.subsystem !== undefined && record.subsystem !== criteria.subsystem) {
+                    return false;
+                }
+                if (criteria.severity !== undefined && record.severity !== criteria.severity) {
+                    return false;
+                }
+                return true;
+            }));
+        },
+        expectCode(code) {
+            if (!records.some((record) => record.code === code)) {
+                throw new Error(`Sloppy TestHost expected diagnostic code '${code}'.`);
+            }
+            return diagnostics;
+        },
+        expectNoSecretLeaks() {
+            const text = JSON.stringify(records);
+            for (const secret of secretTexts) {
+                if (text.includes(secret)) {
+                    throw new Error("Sloppy TestHost diagnostics leaked a configured secret value.");
+                }
+            }
+            return diagnostics;
+        },
+    };
+    return Object.freeze(diagnostics);
+}

package/stdlib/sloppy/internal/testhost-http-server.js

@@ -0,0 +1,238 @@
+import { Text } from "../codec.js";
+import { createHeaderLookup } from "./headers.js";
+import { loopbackAuthority, reserveLoopbackPort } from "./testhost-loopback.js";
+
+const PROBLEM_CONTENT_TYPE = "application/problem+json; charset=utf-8";
+
+function statusText(status) {
+    const titles = {
+        200: "OK",
+        201: "Created",
+        202: "Accepted",
+        204: "No Content",
+        400: "Bad Request",
+        404: "Not Found",
+        500: "Internal Server Error",
+        503: "Service Unavailable",
+    };
+    return titles[status] ?? "Mock Response";
+}
+
+function concatBytes(parts) {
+    const total = parts.reduce((sum, part) => sum + part.byteLength, 0);
+    const result = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.byteLength;
+    }
+    return result;
+}
+
+function indexOfBytes(buffer, needle) {
+    outer:
+    for (let index = 0; index <= buffer.byteLength - needle.byteLength; index += 1) {
+        for (let offset = 0; offset < needle.byteLength; offset += 1) {
+            if (buffer[index + offset] !== needle[offset]) {
+                continue outer;
+            }
+        }
+        return index;
+    }
+    return -1;
+}
+
+async function readMockServerRequest(connection, options = {}) {
+    const chunks = [];
+    const headerEndBytes = Text.utf8.encode("\r\n\r\n");
+    const maxHeaderBytes = options.maxHeaderBytes ?? 64 * 1024;
+    let combined = new Uint8Array(0);
+    let headerEnd = -1;
+    while (headerEnd < 0) {
+        const chunk = await connection.read(8192);
+        if (chunk.byteLength === 0) {
+            throw new Error("Mock HTTP server received a closed connection before request headers.");
+        }
+        chunks.push(chunk);
+        combined = concatBytes(chunks);
+        if (combined.byteLength > maxHeaderBytes) {
+            throw new Error("Mock HTTP server request headers exceeded the configured limit.");
+        }
+        headerEnd = indexOfBytes(combined, headerEndBytes);
+    }
+    const head = Text.utf8.decode(combined.slice(0, headerEnd));
+    const lines = head.split("\r\n");
+    const requestLine = lines.shift() ?? "";
+    const requestMatch = /^([A-Z]+)\s+(\S+)\s+HTTP\/1\.[01]$/u.exec(requestLine);
+    if (requestMatch === null) {
+        throw new Error(`Mock HTTP server received an invalid request line: ${requestLine}`);
+    }
+    const headers = {};
+    for (const line of lines) {
+        const colon = line.indexOf(":");
+        if (colon > 0) {
+            headers[line.slice(0, colon).trim()] = line.slice(colon + 1).trim();
+        }
+    }
+    const headerLookup = createHeaderLookup(headers);
+    const contentLengthText = headerLookup.get("content-length") ?? "0";
+    if (!/^[0-9]+$/u.test(contentLengthText)) {
+        throw new Error("Mock HTTP server received an invalid Content-Length header.");
+    }
+    const contentLength = Number(contentLengthText);
+    const maxBodyBytes = options.maxBodyBytes ?? 4 * 1024 * 1024;
+    if (!Number.isSafeInteger(contentLength) || contentLength > maxBodyBytes) {
+        throw new Error("Mock HTTP server request body exceeded the configured limit.");
+    }
+    const bodyChunks = [];
+    const firstBodyChunk = combined.slice(headerEnd + headerEndBytes.byteLength);
+    let bodyBytesRead = Math.min(firstBodyChunk.byteLength, contentLength);
+    if (bodyBytesRead > 0) {
+        bodyChunks.push(firstBodyChunk.slice(0, bodyBytesRead));
+    }
+    while (bodyBytesRead < contentLength) {
+        const chunk = await connection.read(Math.min(8192, contentLength - bodyBytesRead));
+        if (chunk.byteLength === 0) {
+            throw new Error("Mock HTTP server connection closed before the request body finished.");
+        }
+        bodyChunks.push(chunk);
+        bodyBytesRead += chunk.byteLength;
+    }
+    const body = concatBytes(bodyChunks).slice(0, contentLength);
+    const contentType = headerLookup.get("content-type") ?? "";
+    const text = body.byteLength === 0 ? undefined : Text.utf8.decode(body);
+    const mediaType = contentType.split(";", 1)[0].trim().toLowerCase();
+    let json;
+    if (
+        text !== undefined &&
+        (mediaType === "application/json" || (mediaType.startsWith("application/") && mediaType.endsWith("+json")))
+    ) {
+        json = JSON.parse(text);
+    }
+    return Object.freeze({
+        method: requestMatch[1],
+        url: requestMatch[2],
+        headers,
+        json,
+        text,
+        bytes: body.byteLength === 0 ? undefined : body,
+    });
+}
+
+async function writeMockServerResponse(connection, response) {
+    const headers = { ...response.headers };
+    const headerLookup = createHeaderLookup(headers);
+    if (headerLookup.get("content-length") === undefined) {
+        headers["content-length"] = String(response.body.byteLength);
+    }
+    if (headerLookup.get("connection") === undefined) {
+        headers.connection = "close";
+    }
+    const head = [
+        `HTTP/1.1 ${response.status} ${statusText(response.status)}`,
+        ...Object.entries(headers).map(([name, value]) => `${name}: ${value}`),
+        "",
+        "",
+    ].join("\r\n");
+    await connection.write(Text.utf8.encode(head));
+    if (response.body.byteLength !== 0) {
+        await connection.write(response.body);
+    }
+}
+
+export async function startHttpMockServer(name, mock, options = {}) {
+    const host = options.httpMockHost ?? options.host ?? "127.0.0.1";
+    const reservation = await reserveLoopbackPort(host, {
+        portReservationAttempts: options.httpMockPortReservationAttempts ?? options.portReservationAttempts,
+    });
+    const listener = reservation.listener;
+    const connections = new Set();
+    const activeHandlers = new Set();
+    const timeoutWaiters = new Set();
+    let closed = false;
+
+    function waitForMockTimeout() {
+        if (closed) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            let wake;
+            const timer = setTimeout(() => {
+                timeoutWaiters.delete(wake);
+                resolve();
+            }, options.httpMockTimeoutHoldMs ?? 60000);
+            wake = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            timeoutWaiters.add(wake);
+        });
+    }
+
+    async function handleConnection(connection) {
+        connections.add(connection);
+        try {
+            const request = await readMockServerRequest(connection, options);
+            const response = await mock._dispatchRaw(request);
+            await writeMockServerResponse(connection, response);
+        } catch (error) {
+            if (closed || error?.code === "SLOPPY_E_HTTP_TIMEOUT") {
+                await waitForMockTimeout();
+                return;
+            }
+            const body = Text.utf8.encode(JSON.stringify({
+                code: error?.code ?? "SLOPPY_E_HTTP_MOCK_SERVER",
+                message: "Outbound HTTP mock failed.",
+            }));
+            await writeMockServerResponse(connection, Object.freeze({
+                status: 500,
+                headers: Object.freeze({ "content-type": PROBLEM_CONTENT_TYPE }),
+                body,
+            })).catch(() => {});
+        } finally {
+            await connection.close().catch(() => {});
+            connections.delete(connection);
+        }
+    }
+
+    const serving = (async () => {
+        while (!closed) {
+            try {
+                const connection = await listener.accept({ timeoutMs: 250 });
+                const active = handleConnection(connection).finally(() => {
+                    activeHandlers.delete(active);
+                });
+                activeHandlers.add(active);
+            } catch (error) {
+                if (closed) {
+                    break;
+                }
+                if (/timeout/iu.test(String(error?.message ?? error))) {
+                    continue;
+                }
+                break;
+            }
+        }
+    })();
+
+    return Object.freeze({
+        name,
+        baseUrl: `http://${loopbackAuthority(host, reservation.port)}`,
+        async close() {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            for (const wake of [...timeoutWaiters]) {
+                timeoutWaiters.delete(wake);
+                wake();
+            }
+            await listener.abort().catch(async () => listener.close().catch(() => {}));
+            for (const connection of [...connections]) {
+                await connection.abort().catch(() => {});
+            }
+            await Promise.allSettled([...activeHandlers]);
+            await serving.catch(() => {});
+        },
+    });
+}

package/stdlib/sloppy/internal/testhost-http.js

@@ -0,0 +1,118 @@
+import { copyUint8Array } from "./bytes.js";
+import {
+    assertHeaderToken as assertSharedHeaderToken,
+    assertHeaderValue as assertSharedHeaderValue,
+} from "./headers.js";
+import { isPlainObject, requirePlainObject } from "./validation.js";
+
+export function assertHeaderName(name, subject) {
+    assertSharedHeaderToken(name, `Sloppy test host ${subject}`);
+}
+
+export function assertHeaderValue(value, subject) {
+    assertSharedHeaderValue(value, `Sloppy test host ${subject}`);
+}
+
+export function copyBytes(value, subject) {
+    const bytes = copyUint8Array(value);
+    if (bytes === undefined) {
+        throw new TypeError(`Sloppy test host ${subject} must be a Uint8Array, ArrayBuffer, or ArrayBuffer view.`);
+    }
+    return bytes;
+}
+
+export function headerEntriesFromObject(headers, subject) {
+    if (headers === undefined) {
+        return [];
+    }
+
+    requirePlainObject(headers, `Sloppy test host ${subject} headers must be a plain object.`);
+
+    const entries = [];
+    for (const [name, value] of Object.entries(headers)) {
+        assertHeaderName(name, subject);
+        assertHeaderValue(value, subject);
+        entries.push([name, value]);
+    }
+    return entries;
+}
+
+export function normalizeHeaderEntries(entries) {
+    const normalized = [];
+    const indexes = new Map();
+    for (const [name, value] of entries) {
+        const lower = name.toLowerCase();
+        if (lower === "set-cookie") {
+            normalized.push([lower, value]);
+            continue;
+        }
+        const existingIndex = indexes.get(lower);
+        if (existingIndex === undefined) {
+            indexes.set(lower, normalized.length);
+            normalized.push([lower, value]);
+        } else {
+            normalized[existingIndex][1] = `${normalized[existingIndex][1]}, ${value}`;
+        }
+    }
+    return normalized;
+}
+
+export function createHeadersLike(entries) {
+    const normalized = Object.freeze(normalizeHeaderEntries(entries).map(([name, value]) => Object.freeze([name, value])));
+    const byName = new Map();
+    for (const [name, value] of normalized) {
+        if (!byName.has(name)) {
+            byName.set(name, value);
+        }
+    }
+    return Object.freeze({
+        get(name) {
+            if (typeof name !== "string") {
+                throw new TypeError("Sloppy test host headers.get name must be a string.");
+            }
+            return byName.get(name.toLowerCase());
+        },
+        entries() {
+            return normalized[Symbol.iterator]();
+        },
+        [Symbol.iterator]() {
+            return normalized[Symbol.iterator]();
+        },
+    });
+}
+
+export function headersToEntries(headers) {
+    if (headers === undefined || headers === null) {
+        return [];
+    }
+    if (typeof headers.entries === "function") {
+        return Array.from(headers.entries());
+    }
+    if (isPlainObject(headers)) {
+        return Object.entries(headers);
+    }
+    throw new TypeError("Sloppy test host headers must be response headers or a plain object.");
+}
+
+export function responseHeaderEntries(response, omitEntityHeaders = false) {
+    const entries = [];
+    for (const [name, value] of response.headers.entries()) {
+        const lower = name.toLowerCase();
+        if (omitEntityHeaders && (lower === "content-type" || lower === "content-length")) {
+            continue;
+        }
+        entries.push([name, value]);
+    }
+    return entries;
+}
+
+function hasHeader(entries, name) {
+    const lower = name.toLowerCase();
+    return entries.some(([current]) => current.toLowerCase() === lower);
+}
+
+export function setDefaultHeader(entries, name, value) {
+    if (!hasHeader(entries, name)) {
+        entries.push([name, value]);
+    }
+}

package/stdlib/sloppy/internal/testhost-loopback.js

@@ -0,0 +1,50 @@
+import { Random } from "../crypto.js";
+import { TcpListener } from "../net.js";
+
+const LOOPBACK_PORT_MIN = 49152;
+const LOOPBACK_PORT_MAX = 65535;
+
+export function validateLoopbackPort(port) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new TypeError("Sloppy TestHost loopback port must be an integer from 1 to 65535.");
+    }
+    return port;
+}
+
+function randomLoopbackPort() {
+    const bytes = Random.bytes(2);
+    const value = (bytes[0] << 8) | bytes[1];
+    return LOOPBACK_PORT_MIN + (value % (LOOPBACK_PORT_MAX - LOOPBACK_PORT_MIN + 1));
+}
+
+export async function reserveLoopbackPort(host, options = {}) {
+    if (options.port !== undefined) {
+        const port = validateLoopbackPort(options.port);
+        const listener = await TcpListener.listen({ host, port, backlog: 1 });
+        return { port, listener };
+    }
+    const attempts = options.portReservationAttempts ?? 64;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const port = randomLoopbackPort();
+        try {
+            const listener = await TcpListener.listen({ host, port, backlog: 1 });
+            return { port, listener };
+        } catch {
+            // A different process can own the sampled port; try another reserved candidate.
+        }
+    }
+    throw new Error("Sloppy TestHost could not reserve an available loopback port.");
+}
+
+export async function releaseLoopbackReservation(reservation) {
+    if (reservation?.listener === undefined) {
+        return;
+    }
+    await reservation.listener.close().catch(async () => {
+        await reservation.listener.abort().catch(() => {});
+    });
+}
+
+export function loopbackAuthority(host, port) {
+    return `${String(host).includes(":") ? `[${host}]` : host}:${port}`;
+}

package/stdlib/sloppy/internal/testservices-docker.js

@@ -0,0 +1,154 @@
+import { Text } from "../codec.js";
+import { boundedText } from "./redaction.js";
+import { Process as SloppyProcess } from "../os.js";
+
+function processOutputText(value) {
+    if (value === undefined || value === null) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        return Text.utf8.decode(value);
+    }
+    return String(value);
+}
+
+export class DockerCliBackend {
+    constructor(options = {}) {
+        this.command = options.command ?? "docker";
+        this.cwd = options.cwd;
+        this.env = options.env;
+    }
+
+    async run(args, options = {}) {
+        const result = await SloppyProcess.run(this.command, args, {
+            cwd: options.cwd ?? this.cwd,
+            env: options.env ?? this.env,
+            capture: "bytes",
+            timeoutMs: options.timeoutMs ?? 30000,
+            maxStdoutBytes: options.maxStdoutBytes ?? 1024 * 1024,
+            maxStderrBytes: options.maxStderrBytes ?? 1024 * 1024,
+        });
+        return Object.freeze({
+            exitCode: result.exitCode,
+            stdout: processOutputText(result.stdout),
+            stderr: processOutputText(result.stderr),
+            timedOut: result.timedOut === true,
+        });
+    }
+}
+
+export function dockerBackend(options = undefined) {
+    if (options?.dockerBackend !== undefined) {
+        return options.dockerBackend;
+    }
+    return new DockerCliBackend(options?.docker);
+}
+
+export async function dockerRunOk(backend, args, options = {}) {
+    const result = await backend.run(args, options);
+    if (result.exitCode !== 0 || result.timedOut === true) {
+        const stderr = boundedText(result.stderr || result.stdout);
+        throw new Error(`docker ${args[0]} failed with exit code ${result.exitCode}.${stderr.length === 0 ? "" : `\n${stderr}`}`);
+    }
+    return result;
+}
+
+export function dockerUnavailableError(reason) {
+    const error = new Error(`SLOPPY_E_TESTSERVICES_DOCKER_UNAVAILABLE: Docker is unavailable for Sloppy TestServices.
+
+Reason:
+  ${reason}
+
+Fix:
+  Start Docker Desktop or a compatible Docker daemon, ensure the docker CLI is on PATH, then rerun the opt-in TestServices lane.`);
+    error.code = "SLOPPY_E_TESTSERVICES_DOCKER_UNAVAILABLE";
+    return error;
+}
+
+export async function dockerAvailable(options = {}) {
+    const backend = dockerBackend(options);
+    try {
+        const result = await backend.run(["version", "--format", "{{json .}}"], {
+            timeoutMs: options.timeoutMs ?? 5000,
+            maxStdoutBytes: 64 * 1024,
+            maxStderrBytes: 64 * 1024,
+        });
+        if (result.exitCode !== 0 || result.timedOut === true) {
+            const reason = result.timedOut === true
+                ? "docker version timed out"
+                : boundedText(result.stderr || result.stdout || "docker version failed", 1000);
+            return Object.freeze({ ok: false, available: false, reason });
+        }
+        let version = undefined;
+        try {
+            version = JSON.parse(result.stdout);
+        } catch {
+            version = result.stdout.trim();
+        }
+        return Object.freeze({ ok: true, available: true, reason: undefined, version });
+    } catch (error) {
+        return Object.freeze({
+            ok: false,
+            available: false,
+            reason: String(error?.message ?? error),
+        });
+    }
+}
+
+export async function dockerRequire(options = {}) {
+    const available = await dockerAvailable(options);
+    if (available.ok) {
+        return available;
+    }
+    throw dockerUnavailableError(available.reason);
+}
+
+export async function ensureImage(backend, image, options) {
+    const inspect = await backend.run(["image", "inspect", image], {
+        timeoutMs: options.dockerTimeoutMs ?? 15000,
+        maxStdoutBytes: 64 * 1024,
+        maxStderrBytes: 64 * 1024,
+    });
+    if (inspect.exitCode === 0) {
+        return;
+    }
+    await dockerRunOk(backend, ["pull", image], {
+        timeoutMs: options.pullTimeoutMs ?? 120000,
+        maxStdoutBytes: 256 * 1024,
+        maxStderrBytes: 256 * 1024,
+    });
+}
+
+export function parseInspectJson(text) {
+    const parsed = JSON.parse(text);
+    if (!Array.isArray(parsed) || parsed.length === 0 || parsed[0] === null) {
+        throw new Error("docker inspect returned no container metadata.");
+    }
+    return parsed[0];
+}
+
+export function mappedPortFromInspect(metadata, internalPort) {
+    const ports = metadata?.NetworkSettings?.Ports;
+    const entries = ports?.[`${internalPort}/tcp`];
+    if (!Array.isArray(entries) || entries.length === 0) {
+        throw new Error(`docker inspect did not report a mapped host port for ${internalPort}/tcp.`);
+    }
+    const hostPort = Number(entries[0].HostPort);
+    if (!Number.isInteger(hostPort) || hostPort < 1 || hostPort > 65535) {
+        throw new Error(`docker inspect returned an invalid host port for ${internalPort}/tcp.`);
+    }
+    return hostPort;
+}
+
+export async function inspectContainer(backend, containerId, internalPort, options) {
+    const result = await dockerRunOk(backend, ["inspect", containerId], {
+        timeoutMs: options.dockerTimeoutMs ?? 15000,
+        maxStdoutBytes: 256 * 1024,
+        maxStderrBytes: 64 * 1024,
+    });
+    const metadata = parseInspectJson(result.stdout);
+    return { metadata, port: mappedPortFromInspect(metadata, internalPort) };
+}