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

package/examples/http-client-resilience/README.md

@@ -0,0 +1,4 @@
+# HTTP Client Resilience
+
+This example configures retry, circuit-breaker, and bulkhead policies for a
+named outbound client. Unsafe methods are not retried by default.

package/examples/http-client-resilience/app.js

@@ -0,0 +1,38 @@
+import { Http } from "sloppy/http";
+
+const orders = Http.client("orders", {
+    baseUrl: "https://orders.internal",
+    timeoutMs: 2000,
+    retry: Http.retry.exponential({
+        maxAttempts: 3,
+        initialDelayMs: 100,
+        maxDelayMs: 2000,
+        jitter: true,
+        retryOnStatus: [408, 429, 500, 502, 503, 504],
+        retryOnMethods: ["GET", "HEAD", "PUT", "DELETE"],
+    }),
+    circuitBreaker: Http.circuitBreaker({
+        failureRatio: 0.5,
+        minimumThroughput: 20,
+        samplingWindowMs: 30000,
+        breakDurationMs: 30000,
+    }),
+    bulkhead: Http.bulkhead({
+        maxConcurrent: 32,
+        maxQueue: 128,
+        queueTimeoutMs: 1000,
+    }),
+    pool: {
+        maxConnectionsPerOrigin: 32,
+        idleTimeoutMs: 60000,
+        connectionLifetimeMs: 300000,
+    },
+});
+
+async function loadOrder(id, signal) {
+    return await orders
+        .get("/orders/{id}", { params: { id }, signal })
+        .json();
+}
+
+export { loadOrder, orders };

package/examples/http-client-runtime-loopback/README.md

@@ -0,0 +1,24 @@
+# Runtime Loopback HTTP Client
+
+This example documents the native-backed outbound loopback path used by the
+low-level HTTP client tests.
+
+```js
+import { HttpClient } from "sloppy/net";
+
+const client = HttpClient.create({
+    baseUrl: "http://127.0.0.1:8080",
+    pool: {
+        maxConnectionsPerOrigin: 4,
+        pendingQueueTimeoutMs: 1000,
+    },
+});
+
+const response = await client.get("/health");
+console.log(await response.text());
+await client.close();
+```
+
+`tests/bootstrap/test_http_client.mjs` covers local loopback GET requests,
+pool reuse, queue timeout/cancellation, client close behavior, and response body
+limits using the runtime TCP bridge exposed to the bootstrap test harness.

package/examples/http-client-testhost/README.md

@@ -0,0 +1,4 @@
+# HTTP Client TestHost
+
+This example tests a typed outbound client through `TestHost` with
+`TestHttp.mock()`. No external HTTP mocking package is needed.

package/examples/http-client-testhost/app.js

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+
+import { app } from "../http-client-typed/app.js";
+import { TestHost, TestHttp } from "sloppy";
+
+const billing = TestHttp.mock()
+    .get("/invoices/inv_1")
+    .replyJson(200, { id: "inv_1", status: "paid", amount: 42 });
+
+const host = await TestHost.create(app, {
+    config: {
+        "Billing:BaseUrl": "http://billing.test",
+    },
+    httpClients: {
+        billing,
+    },
+});
+
+try {
+    const response = await host.get("/invoices/inv_1").expectStatus(200);
+    await response.expectJson({ id: "inv_1", status: "paid", amount: 42 });
+    billing.expectCalled("GET", "/invoices/inv_1").expectNoUnexpectedCalls();
+} finally {
+    await host.close();
+}
+
+assert.equal(true, true);

package/examples/http-client-testhost-package-mock/README.md

@@ -0,0 +1,26 @@
+# TestHost Package HTTP Mock
+
+`TestHost.fromArtifacts(...)`, `TestHost.fromPackage(...)`, and loopback modes
+accept `httpClients` overrides.
+
+```js
+import { TestHost, TestHttp } from "sloppy";
+
+const billing = TestHttp.mock()
+    .get("/invoices/inv_1")
+    .replyJson(200, { id: "inv_1", status: "paid", amount: 42 });
+
+const host = await TestHost.fromArtifacts(".sloppy", {
+    httpClients: { billing },
+});
+
+await host.get("/route-that-calls-billing").expectStatus(200);
+billing.expectCalled("GET", "/invoices/inv_1").expectNoUnexpectedCalls();
+await host.close();
+```
+
+For artifact and package hosts, TestHost starts a local loopback mock server and
+injects the generated base URL through config environment variables such as
+`Billing__BaseUrl`. Handler execution in this example requires a V8-enabled
+`sloppy` CLI; the process-host harness is covered by
+`tests/bootstrap/test_testhost_process_modes.mjs`.

package/examples/http-client-typed/README.md

@@ -0,0 +1,5 @@
+# HTTP Client Typed
+
+This example shows a typed outbound client registered with Sloppy services.
+The typed client validates path params before sending and validates the JSON
+response before returning it to the route handler.

package/examples/http-client-typed/app.js

@@ -0,0 +1,33 @@
+import { Config, Http, Results, schema, Sloppy } from "sloppy";
+
+const BillingInvoice = schema.object({
+    id: schema.string(),
+    status: schema.string(),
+    amount: schema.number(),
+});
+
+const Billing = Http.typedClient("billing", {
+    baseUrl: Config.required("Billing:BaseUrl"),
+    timeoutMs: 2000,
+    endpoints: {
+        getInvoice: Http.get("/invoices/{id}")
+            .params(schema.object({ id: schema.string() }))
+            .returns(200, BillingInvoice),
+    },
+});
+
+const app = Sloppy.create();
+
+app.services.addHttpClient(Billing);
+
+app.get("/invoices/{id}", async (ctx) => {
+    const billing = ctx.services.get(Billing);
+    const invoice = await billing.getInvoice(
+        { id: ctx.route.id },
+        { signal: ctx.signal, correlationId: ctx.requestId },
+    );
+
+    return Results.json(invoice);
+});
+
+export { app, Billing };

package/examples/modules-api/README.md

@@ -0,0 +1,30 @@
+# Modules API Example
+
+This is a compile-time source-input example for multi-file function modules.
+Run from this directory:
+
+```powershell
+..\..\build\windows-dev\sloppy.exe run
+```
+
+The command compiles through `sloppy.json` and emits `.sloppy\app.plan.json`. Non-V8 builds
+stop at the expected V8-required diagnostic after artifact emission; V8 builds can execute
+the emitted route handlers.
+
+Routes:
+
+- `GET /health`
+- `GET /users`
+- `GET /users/{id}`
+
+The example demonstrates relative module imports, multiple function modules from one module file,
+route groups, module-attributed Plan routes, route binding, explicit `Results` helpers, and
+routes/doctor/openapi metadata over a multi-file source graph.
+
+This is the function-module source-input subset. It is intentionally distinct from the
+bootstrap `Sloppy.module(...)` capability/service module shape used by other examples.
+
+## Limitations
+
+Controller/decorator routing, DI container behavior, dynamic imports, package
+resolution, and runtime module loading are outside this example.

package/examples/modules-api/app.js

@@ -0,0 +1,9 @@
+import { Sloppy } from "sloppy";
+import { healthModule, usersModule } from "./modules/routes.js";
+
+const app = Sloppy.create();
+
+app.useModule(healthModule);
+app.useModule(usersModule);
+
+export default app;

package/examples/modules-api/modules/routes.js

@@ -0,0 +1,16 @@
+import { Results } from "sloppy";
+
+export function healthModule(app) {
+    const health = app.group("/health");
+
+    health.get("/", () => Results.text("ok")).withName("Health.Get");
+}
+
+export function usersModule(app) {
+    const users = app.group("/users");
+
+    users.get("/", () => Results.json([{ id: "demo", name: "Demo User" }]))
+        .withName("Users.List");
+    users.get("/{id}", (ctx) => Results.json({ id: ctx.route.id, name: "Demo User" }))
+        .withName("Users.Get");
+}

package/examples/modules-api/sloppy.json

@@ -0,0 +1,5 @@
+{
+  "entry": "app.js",
+  "outDir": ".sloppy",
+  "environment": "Development"
+}

package/examples/modules-basic/README.md

@@ -0,0 +1,32 @@
+# Modules Basic Example
+
+Bootstrap module example.
+This example shows module composition with `Sloppy.module(...)`, `dependsOn`, services,
+routes, metadata, and `builder.addModule(...)`.
+
+- `DataModule` registers a fake in-memory service.
+- `UsersModule` declares `.dependsOn("data")`.
+- module services and routes are applied by `builder.addModule(...)` during `builder.build()`.
+- module-created routes and services appear in bootstrap debug metadata.
+
+What to inspect:
+
+- import from the checked-in bootstrap stdlib source path;
+- create modules with dependencies, services, routes, and metadata;
+- add modules to a builder;
+- inspect routes with `app.__getRoutes()`;
+- inspect module debug metadata with `app.__debug().modules`.
+
+Current product state:
+
+- This source-stdlib example is a checked-in API-shape fixture.
+- `sloppy run --artifacts` currently runs emitted artifacts such as
+  `examples/compiler-hello`.
+- `sloppyc` compilation and `app.plan.json` emission for this module shape are future
+  source-extraction work.
+- The bounded `sloppy run` path currently loads generated artifacts, not this
+  source-stdlib module example.
+- The `data` module is an in-memory service example. Real providers are covered by the
+  provider examples and data API tests.
+- Module package loading and native plugins belong to later module/package work.
+- Bare `"sloppy"` imports are the current source shape for this example.

package/examples/modules-basic/app.js

@@ -0,0 +1,41 @@
+import { Sloppy, Results } from "sloppy";
+
+export const DataModule = Sloppy.module("data")
+    .metadata("description", "in-memory demo data service")
+    .services((services) => {
+        services.addSingleton("data.users", () => new Map([
+            ["demo", { id: "demo", name: "Demo User" }],
+        ]));
+    });
+
+export const UsersModule = Sloppy.module("users")
+    .dependsOn("data")
+    .metadata("area", "users")
+    .services((services) => {
+        services.addSingleton("users.message", () => "hello from a module");
+    })
+    .routes((app) => {
+        app.mapGroup("/users")
+            .withTags("Users")
+            .mapGet("/{id:int}", ({ route, services }) => {
+                const users = services.get("data.users");
+                const id = route.id ?? "demo";
+
+                return Results.ok({
+                    ...users.get(id),
+                    id,
+                    message: services.get("users.message"),
+                });
+            })
+            .withName("Users.Get");
+    });
+
+const builder = Sloppy.createBuilder();
+
+builder
+    .addModule(UsersModule)
+    .addModule(DataModule);
+
+const app = builder.build();
+
+export default app;

package/examples/net-deadline-cancel/README.md

@@ -0,0 +1,13 @@
+# TCP Deadline And Cancellation Example
+
+This source example shows `TcpClient.connect` with `Deadline.after`,
+`CancellationController`, connect timeout, read/write deadline options, signal options,
+and cleanup after timeout or cancellation.
+
+Late completions are cleanup-only in the runtime contract.
+
+## Limitations
+
+This example is limited to TCP deadlines and cancellation. TLS, HTTP, UDP,
+WebSocket, local IPC, and external live-network behavior are outside this
+example.

package/examples/net-deadline-cancel/app.js

@@ -0,0 +1,34 @@
+import { TcpClient } from "sloppy/net";
+import { CancellationController, Deadline } from "sloppy/time";
+
+export async function pingWithDeadline(appSignal) {
+  const deadline = Deadline.after(500);
+  const conn = await TcpClient.connect({
+    host: "127.0.0.1",
+    port: 6379,
+    timeoutMs: 500,
+    deadline,
+    signal: appSignal
+  });
+
+  try {
+    await conn.writeText("PING\r\n", { deadline, signal: appSignal });
+    return await conn.readLine({ deadline, signal: appSignal });
+  }
+  finally {
+    await conn.close();
+  }
+}
+
+export async function cancelPendingConnect() {
+  const controller = new CancellationController();
+  const pending = TcpClient.connect({
+    host: "127.0.0.1",
+    port: 6379,
+    timeoutMs: 5000,
+    signal: controller.signal
+  });
+
+  controller.cancel("request cancelled");
+  return await pending;
+}

package/examples/net-local-ipc/README.md

@@ -0,0 +1,12 @@
+# Local IPC Example
+
+This source example shows the scoped `sloppy/net` local IPC API shape:
+`LocalEndpoint.listen`, `LocalEndpoint.connect`, async iterable accept, bounded byte
+reads/writes, delimiter reads that preserve binary data, deadline/cancellation options,
+stale cleanup intent, permissions where supported, and explicit `UnixSocket`/`NamedPipe`
+entry points.
+
+## Limitations
+
+TLS, HTTP, UDP, WebSocket, external live-network behavior, and Windows AF_UNIX
+portability are outside this example.

package/examples/net-local-ipc/app.js

@@ -0,0 +1,46 @@
+import { LocalEndpoint, NamedPipe, UnixSocket } from "sloppy/net";
+import { CancellationController, Deadline } from "sloppy/time";
+
+export async function runLocalEcho() {
+  const controller = new CancellationController();
+  const signal = controller.signal;
+  const deadline = Deadline.after(1000);
+  const server = await LocalEndpoint.listen({
+    path: "runtime:/local-echo.sock",
+    unlinkExisting: true,
+    permissions: "0600",
+    backlog: 8
+  });
+
+  const accepted = (async () => {
+    for await (const conn of server.accept({ signal, deadline })) {
+      try {
+        const payload = await conn.readUntil(new Uint8Array([0]), { maxBytes: 65536, deadline, signal });
+        await conn.write(payload, { deadline, signal });
+      }
+      finally {
+        await conn.close();
+      }
+      break;
+    }
+  })();
+
+  const client = await LocalEndpoint.connect({ path: "runtime:/local-echo.sock", deadline, signal });
+  try {
+    await client.write(new Uint8Array([1, 2, 0]), { deadline, signal });
+    return await client.read({ maxBytes: 3, deadline, signal });
+  }
+  finally {
+    await client.close();
+    controller.cancel("local echo complete");
+    await accepted;
+    await server.close();
+    controller.dispose();
+  }
+}
+
+export async function connectPlatformSpecific() {
+  const unix = UnixSocket.connect({ path: "runtime:/daemon.sock" });
+  const pipe = NamedPipe.connect({ path: "runtime:/daemon.sock" });
+  return { unix, pipe };
+}

package/examples/net-policy-strict/README.md

@@ -0,0 +1,12 @@
+# Strict Network Policy Example
+
+This source example shows the intended Plan-visible shape for strict network access:
+literal connect/listen targets, explicit access grants, loopback listen metadata, and
+bounded admission before socket work.
+
+The policy object is example metadata, not a package manifest or an OS sandbox.
+
+## Limitations
+
+External live-network access, TLS, HTTP, UDP, WebSocket, local IPC, and secret
+endpoint handling are outside this example.

package/examples/net-policy-strict/app.js

@@ -0,0 +1,34 @@
+import { TcpClient, TcpListener } from "sloppy/net";
+
+export const strictNetworkPolicy = {
+  mode: "strict",
+  allow: [
+    { access: "connect", host: "10.0.0.25", port: 6379 },
+    { access: "listen", host: "127.0.0.1", port: 9000 }
+  ]
+};
+
+export async function connectToAllowedCache() {
+  return await TcpClient.connect({
+    host: "10.0.0.25",
+    port: 6379,
+    timeoutMs: 1000
+  });
+}
+
+export async function listenOnAllowedLoopback(signal) {
+  const listener = await TcpListener.listen({
+    host: "127.0.0.1",
+    port: 9000,
+    backlog: 16
+  });
+
+  try {
+    for await (const conn of listener.accept({ signal })) {
+      await conn.close();
+    }
+  }
+  finally {
+    await listener.close();
+  }
+}

package/examples/net-tcp-client/README.md

@@ -0,0 +1,10 @@
+# TCP Client Example
+
+This source example shows the scoped `sloppy/net` TCP client API shape for a
+loopback service: `NetworkAddress.parse`, `TcpClient.connect`, `writeText`,
+`readLine`, deadline propagation, `noDelay`, `keepAlive`, and deterministic close.
+
+## Limitations
+
+TLS, HTTP, UDP, WebSocket, and external live-network behavior are outside this
+example.

package/examples/net-tcp-client/app.js

@@ -0,0 +1,23 @@
+import { TcpClient, NetworkAddress } from "sloppy/net";
+import { Deadline } from "sloppy/time";
+
+export async function pingRedisLikeService() {
+  const target = NetworkAddress.parse("127.0.0.1:6379");
+  const deadline = Deadline.after(1000);
+  const conn = await TcpClient.connect({
+    host: target.host,
+    port: target.port,
+    timeoutMs: 1000,
+    noDelay: true,
+    keepAlive: { enabled: true, delayMs: 30000 },
+    deadline
+  });
+
+  try {
+    await conn.writeText("PING\r\n");
+    return await conn.readLine({ deadline });
+  }
+  finally {
+    await conn.close();
+  }
+}

package/examples/net-tcp-echo/README.md

@@ -0,0 +1,11 @@
+# TCP Echo Example
+
+This source example keeps the echo loop in scoped TCP runtime behavior: ephemeral loopback
+listen, async accept, `readChunks`, bounded read/write calls, endpoint metadata, and
+cleanup for accepted and outbound connections.
+
+## Limitations
+
+This example is limited to scoped TCP echo behavior. Throughput benchmarks,
+stress/torture runs, TLS, HTTP, UDP, WebSocket, local IPC, and external
+live-network behavior are outside this example.

package/examples/net-tcp-echo/app.js

@@ -0,0 +1,45 @@
+import { TcpClient, TcpListener } from "sloppy/net";
+
+export async function startEcho(signal) {
+  const listener = await TcpListener.listen({
+    host: "127.0.0.1",
+    port: 0,
+    backlog: 32
+  });
+
+  runEchoAcceptLoop(listener, signal);
+  return listener;
+}
+
+async function runEchoAcceptLoop(listener, signal) {
+  for await (const conn of listener.accept({ signal })) {
+    echoConnection(conn);
+  }
+}
+
+async function echoConnection(conn) {
+  try {
+    for await (const chunk of conn.readChunks({ maxBytes: 65536 })) {
+      await conn.write(chunk);
+    }
+  }
+  finally {
+    await conn.close();
+  }
+}
+
+export async function echoOnce(listener, payload) {
+  const endpoint = listener.localAddress;
+  const conn = await TcpClient.connect({
+    host: endpoint.host,
+    port: endpoint.port
+  });
+
+  try {
+    await conn.write(payload);
+    return await conn.read({ maxBytes: payload.length });
+  }
+  finally {
+    await conn.close();
+  }
+}

package/examples/net-tcp-server/README.md

@@ -0,0 +1,10 @@
+# TCP Server Example
+
+This source example shows `TcpListener.listen`, loopback binding, backlog metadata,
+async iterable `accept`, accepted connection ownership, line reads, text writes, and
+listener cleanup.
+
+## Limitations
+
+This example is limited to scoped TCP listener behavior. Local IPC, TLS, HTTP,
+UDP, WebSocket, and external live-network behavior are outside this example.

package/examples/net-tcp-server/app.js

@@ -0,0 +1,28 @@
+import { TcpListener } from "sloppy/net";
+
+export async function serveLines(appSignal) {
+  const listener = await TcpListener.listen({
+    host: "127.0.0.1",
+    port: 9000,
+    backlog: 128
+  });
+
+  try {
+    for await (const conn of listener.accept({ signal: appSignal })) {
+      handleConnection(conn);
+    }
+  }
+  finally {
+    await listener.close();
+  }
+}
+
+async function handleConnection(conn) {
+  try {
+    const line = await conn.readLine();
+    await conn.writeText(line);
+  }
+  finally {
+    await conn.close();
+  }
+}

package/examples/node-compat-path-events/README.md

@@ -0,0 +1,15 @@
+# Node Shims: path and events
+
+This example imports two supported Node compatibility shims:
+
+- `node:path`
+- `node:events`
+
+It demonstrates explicit compatibility modules. Sloppy does not provide a full
+Node runtime or implicit Node globals.
+
+```sh
+sloppy build
+sloppy deps .sloppy
+sloppy run
+```

package/examples/node-compat-path-events/sloppy.json

@@ -0,0 +1,6 @@
+{
+  "kind": "program",
+  "entry": "src/main.ts",
+  "outDir": ".sloppy",
+  "environment": "Development"
+}

package/examples/node-compat-path-events/src/main.ts

@@ -0,0 +1,15 @@
+import path from "node:path";
+import { EventEmitter } from "node:events";
+
+export function main() {
+    const bus = new EventEmitter();
+    let seen = "";
+
+    bus.on("ready", (value) => {
+        seen = path.join("plugins", value);
+    });
+
+    bus.emit("ready", "alpha.js");
+    console.log(seen);
+    return 0;
+}

package/examples/ops-compiler/README.md

@@ -0,0 +1,9 @@
+# Ops Compiler Example
+
+This example uses compiler-visible health and management configuration so Plan,
+routes, doctor, audit, package, and run tooling can see the operations endpoints.
+
+This is a test-only audit fixture. It intentionally leaves detailed management
+endpoints unprotected in source so doctor and audit can report the exposure in
+generated artifact checks. Recommended application code should use the protected
+app-host pattern shown in `examples/ops-health-metrics-management`.