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

package/examples/time-interval-schedule/app.js

@@ -0,0 +1,60 @@
+import { Time } from "sloppy/time";
+
+const ticks = [];
+const runs = [];
+const startedRuns = [];
+
+let resolveStartedRuns;
+const started = new Promise((resolve) => {
+    resolveStartedRuns = resolve;
+});
+
+function markStarted(name) {
+    startedRuns.push(name);
+    if (startedRuns.length === 2) {
+        resolveStartedRuns();
+    }
+}
+
+for await (const tick of Time.interval(1000, { immediate: true, maxTicks: 3 })) {
+    ticks.push(tick.index);
+}
+
+const job = Time.every(
+    "5m",
+    async (ctx) => {
+        runs.push(ctx.run);
+        markStarted("job");
+        await cleanup({ signal: ctx.signal });
+    },
+    {
+        immediate: true,
+        noOverlap: true,
+        missedRunPolicy: "skip",
+        maxRuns: 1,
+    },
+);
+
+const scheduledJob = Time.every("5m", async (ctx) => {
+    markStarted("scheduledJob");
+    return cleanup({ signal: ctx.signal });
+}, {
+    immediate: true,
+    noOverlap: true,
+    missedRunPolicy: "skip",
+    maxRuns: 1,
+});
+
+await started;
+await job.stop();
+await scheduledJob.stop();
+
+async function cleanup({ signal }) {
+    if (signal.aborted) {
+        return "cancelled";
+    }
+    await Time.yield();
+    return "clean";
+}
+
+export default { ticks, runs, startedRuns, skippedRuns: job.skippedRuns };

package/examples/users-api-sqlite/README.md

@@ -0,0 +1,74 @@
+# SQLite Users API Example
+
+## What This Demonstrates
+
+This example shows a small SQLite-backed users API using the supported classic
+artifact path:
+
+- `GET /health`;
+- `GET /users`;
+- `GET /users/{id}`;
+- `POST /users`;
+- explicit `sqlite("main")` provider registration;
+- a relative function module under `modules/users.js`;
+- `sloppy.json` and `appsettings.json` project configuration.
+
+## Requirements
+
+- A V8-enabled `sloppy` runtime.
+- SQLite bridge support in that runtime.
+
+## Run
+
+From this example directory:
+
+```powershell
+..\..\build\windows-relwithdebinfo\sloppy.exe run --once GET /users
+```
+
+From the repository root:
+
+```powershell
+.\build\windows-relwithdebinfo\sloppy.exe run examples/users-api-sqlite/app.js --once GET /users
+```
+
+## Expected Result
+
+The response body is JSON with the seeded users. The exact rows can include
+users inserted by earlier requests when the configured database file is reused.
+
+```json
+[{"id":1,"name":"Ada Lovelace","email":"ada@example.test"},{"id":2,"name":"Grace Hopper","email":"grace@example.test"}]
+```
+
+## What To Inspect
+
+- `app.js`: app creation, SQLite descriptor registration, and route wiring.
+- `modules/users.js`: `app.provider("sqlite:main")` and users route handlers.
+- `sloppy.json`: source-input project configuration.
+- `appsettings.json`: SQLite provider database setting.
+- Generated `.sloppy/app.plan.json`: route, module, provider, capability, and
+  source-location metadata.
+
+After building artifacts, these commands inspect the Plan:
+
+```powershell
+..\..\build\windows-dev\sloppy.exe routes --plan .sloppy\app.plan.json
+..\..\build\windows-dev\sloppy.exe capabilities --plan .sloppy\app.plan.json
+..\..\build\windows-dev\sloppy.exe doctor --plan .sloppy\app.plan.json
+..\..\build\windows-dev\sloppy.exe audit --plan .sloppy\app.plan.json --format json
+..\..\build\windows-dev\sloppy.exe openapi --plan .sloppy\app.plan.json
+```
+
+## Current Limits
+
+This example focuses on SQLite provider integration and localhost transport flow. PostgreSQL
+and SQL Server are covered by separate examples, and streaming APIs are not included in
+this slice.
+
+## Related Docs
+
+- `docs/guide/sqlite.md`
+- `docs/api/data.md`
+- `docs/reference/providers.md`
+- `docs/reference/framework.md`

package/examples/users-api-sqlite/app.js

@@ -0,0 +1,11 @@
+import { Sloppy, Results } from "sloppy";
+import { sqlite } from "sloppy/providers/sqlite";
+import { usersModule } from "./modules/users.js";
+
+const app = Sloppy.create();
+
+app.use(sqlite("main"));
+app.get("/health", () => Results.text("ok"));
+app.useModule(usersModule);
+
+export default app;

package/examples/users-api-sqlite/appsettings.Development.json

@@ -0,0 +1,11 @@
+{
+  "Sloppy": {
+    "Providers": {
+      "sqlite": {
+        "main": {
+          "database": "users-api-sqlite-runtime.db"
+        }
+      }
+    }
+  }
+}

package/examples/users-api-sqlite/appsettings.json

@@ -0,0 +1,11 @@
+{
+  "Sloppy": {
+    "Providers": {
+      "sqlite": {
+        "main": {
+          "database": "users-api-sqlite-runtime.db"
+        }
+      }
+    }
+  }
+}

package/examples/users-api-sqlite/modules/users.js

@@ -0,0 +1,40 @@
+import { Results } from "sloppy";
+
+export function usersModule(app) {
+    const db = app.provider("sqlite:main");
+    const users = app.group("/users");
+
+    users.get("/", async () => {
+        await db.exec("create table if not exists users (id integer primary key, name text not null, email text not null unique)", []);
+        await db.exec("insert into users (id, name, email) select ?, ?, ? where not exists (select 1 from users where id = ?)", [1, "Ada Lovelace", "ada@example.test", 1]);
+        await db.exec("insert into users (id, name, email) select ?, ?, ? where not exists (select 1 from users where id = ?)", [2, "Grace Hopper", "grace@example.test", 2]);
+        return Results.json(await db.query("select id, name, email from users order by id", []));
+    }).withName("Users.List");
+
+    users.get("/{id:int}", async (ctx) => {
+        await db.exec("create table if not exists users (id integer primary key, name text not null, email text not null unique)", []);
+        await db.exec("insert into users (id, name, email) select ?, ?, ? where not exists (select 1 from users where id = ?)", [1, "Ada Lovelace", "ada@example.test", 1]);
+        await db.exec("insert into users (id, name, email) select ?, ?, ? where not exists (select 1 from users where id = ?)", [2, "Grace Hopper", "grace@example.test", 2]);
+        const user = await db.queryOne("select id, name, email from users where id = ?", [ctx.route.id]);
+        return user === null ? Results.notFound({ error: "user_not_found" }) : Results.json(user);
+    }).withName("Users.Get");
+
+    users.post("/", async (ctx) => {
+        const body = ctx.request.json();
+        if (body === null || Array.isArray(body) || typeof body !== "object" ||
+            typeof body.name !== "string" || body.name.length === 0 ||
+            typeof body.email !== "string" || body.email.length === 0) {
+            return Results.problem(
+                { title: "Invalid user payload", detail: "name and email are required" },
+                { status: 400 },
+            );
+        }
+
+        await db.exec("create table if not exists users (id integer primary key, name text not null, email text not null unique)", []);
+        await db.exec("insert into users (id, name, email) select ?, ?, ? where not exists (select 1 from users where id = ?)", [1, "Ada Lovelace", "ada@example.test", 1]);
+        await db.exec("insert into users (id, name, email) select ?, ?, ? where not exists (select 1 from users where id = ?)", [2, "Grace Hopper", "grace@example.test", 2]);
+        await db.exec("insert into users (name, email) values (?, ?)", [body.name, body.email]);
+        const user = await db.queryOne("select id, name, email from users where id = last_insert_rowid()", []);
+        return Results.created(`/users/${user.id}`, user);
+    }).withName("Users.Create");
+}

package/examples/users-api-sqlite/sloppy.json

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

package/examples/validation-errors/README.md

@@ -0,0 +1,36 @@
+# Validation Errors Example
+
+This is a Plan/OpenAPI metadata example plus native Plan-backed validation fixture for
+schema-backed body bindings.
+
+Build artifacts from this directory:
+
+```powershell
+..\..\compiler\target\debug\sloppyc.exe build app.js --out .sloppy
+```
+
+Then inspect the Plan-driven tooling:
+
+```powershell
+..\..\build\windows-dev\sloppy.exe routes --plan .sloppy\app.plan.json
+..\..\build\windows-dev\sloppy.exe doctor --plan .sloppy\app.plan.json
+..\..\build\windows-dev\sloppy.exe openapi --plan .sloppy\app.plan.json
+```
+
+Route:
+
+- `POST /users`
+
+The example demonstrates schema declaration extraction, `ctx.body.json(UserCreate)` request body
+metadata, validation problem OpenAPI components, explicit partial/known metadata reporting,
+and the request shape consumed by the native Plan-backed validation foundation.
+`invalid-user.http` is a documentation fixture for the intended invalid request shape.
+
+The native runtime now has a bounded Plan-backed validation path for route/query/header
+scalars and schema-backed JSON request bodies.
+
+## Limitations
+
+This example focuses on validation metadata and Plan-backed request validation. Typed
+handler execution, provider/DI integration, custom validators, native JSON fast paths, and
+broader HTTP features are outside this slice.

package/examples/validation-errors/app.js

@@ -0,0 +1,14 @@
+import { Sloppy, Results, schema } from "sloppy";
+
+const UserCreate = schema.object({
+    name: schema.string().min(1),
+    email: schema.string().email(),
+});
+
+const app = Sloppy.create();
+
+app.post("/users", (ctx) => Results.created("/users/1", {
+    user: ctx.body.json(UserCreate),
+})).withName("Users.Create");
+
+export default app;

package/examples/validation-errors/invalid-user.http

@@ -0,0 +1,6 @@
+POST /users HTTP/1.1
+Host: localhost
+Content-Type: application/json
+Content-Length: 2
+
+{}

package/examples/validation-errors/sloppy.json

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

package/examples/web-dynamic-routes/README.md

@@ -0,0 +1,17 @@
+# Dynamic Web Routes
+
+This example mixes one statically understood route with route registrations
+that execute at startup.
+
+```powershell
+sloppyc build examples/web-dynamic-routes/app.ts --out .sloppy
+sloppy routes .sloppy
+sloppy openapi .sloppy --output openapi.json
+sloppy run .sloppy --once GET /health
+```
+
+`/health` has complete route metadata. The loop, computed path, conditional
+registration, and dynamic status response stay runnable when V8 is enabled, but
+the Plan marks their route metadata as dynamic and emits
+`SLOPPYC_W_DYNAMIC_ROUTE` findings. OpenAPI includes only routes it can
+represent safely.

package/examples/web-dynamic-routes/app.ts

@@ -0,0 +1,27 @@
+import { Results, Sloppy } from "sloppy";
+import { Environment } from "sloppy/os";
+
+const app = Sloppy.create();
+
+app.get("/health", () => Results.text("ok")).withName("Health.Get");
+
+const routes = [
+    ["/hello/Ada", () => Results.json({ hello: "Ada" })],
+    ["/hello/Grace", () => Results.json({ hello: "Grace" })],
+] as const;
+
+for (const [path, handler] of routes) {
+    app.get(path, handler);
+}
+
+function getStatusPath() {
+    return "/status";
+}
+
+app.get(getStatusPath(), () => Results.status(Date.now() % 2 === 0 ? 200 : 201));
+
+if (Environment.get("ENABLE_ADMIN") === "true") {
+    app.get("/admin/status", () => Results.text("admin ok"));
+}
+
+export default app;

package/examples/webhooks-basic/README.md

@@ -0,0 +1,11 @@
+# Webhooks Basic
+
+This example shows the public API shape for event descriptors, outbox
+registration, transactional publish, and delivery worker wiring.
+
+It is source-level documentation for the pre-alpha runtime. Run the bootstrap
+webhook tests for executable coverage:
+
+```powershell
+node tests/bootstrap/test_webhooks.mjs
+```

package/examples/webhooks-basic/app.js

@@ -0,0 +1,48 @@
+import { Config, Http, Results, Sloppy, Webhooks, schema } from "sloppy";
+
+const OrderCreated = Webhooks.event("order.created", {
+    version: 1,
+    schema: schema.object({
+        orderId: schema.string(),
+        customerId: schema.string(),
+        total: schema.number(),
+    }),
+});
+
+const builder = Sloppy.createBuilder();
+
+builder.services.addHttpClient(Http.client("webhooks", {
+    baseUrl: Config.required("Webhooks:BaseUrl"),
+    retry: Http.retry.none(),
+}));
+
+builder.services.addWebhooks(Webhooks.outbox({
+    provider: "main",
+    signingSecret: Config.requiredSecret("Webhooks:SigningSecret"),
+    delivery: {
+        client: "webhooks",
+        retry: Webhooks.retry.exponential({
+            maxAttempts: 8,
+            initialDelayMs: 1000,
+            maxDelayMs: 300000,
+        }),
+    },
+}));
+
+const app = builder.build();
+
+app.post("/orders", async (ctx) => {
+    const order = await ctx.services.get("data.main").transaction(async (tx) => {
+        const created = { id: "ord_1", customerId: "cus_1", total: 42 };
+        await ctx.webhooks.publish(tx, OrderCreated, {
+            orderId: created.id,
+            customerId: created.customerId,
+            total: created.total,
+        });
+        return created;
+    });
+
+    return Results.created(`/orders/${order.id}`, order);
+});
+
+export default app;

package/examples/websocket-auth/README.md

@@ -0,0 +1,8 @@
+# WebSocket Auth
+
+Protected WebSocket route using JWT bearer auth and a required `realtime`
+scope. Test it with `host.websocket("/secure/ws").withJwt(...)`.
+
+Native WebSocket routes fail closed when the route requires auth until the auth
+principal bridge is attached to upgraded connections. Use TestHost for this
+protected-route example.

package/examples/websocket-auth/app.js

@@ -0,0 +1,16 @@
+import { Auth, Sloppy } from "sloppy";
+
+const app = Sloppy.create();
+
+app.use(Auth.jwtBearer({
+    secret: "test-secret",
+}));
+
+app.websocket("/secure/ws", async (socket) => {
+    const user = socket.ctx.requireUser();
+    await socket.accept();
+    await socket.sendJson({ type: "hello", sub: user.sub });
+    await socket.close();
+}).requiresAuth().requiresScope("realtime");
+
+export default app;

package/examples/websocket-echo/README.md

@@ -0,0 +1,9 @@
+# WebSocket Echo
+
+WebSocket echo endpoint with text, JSON, schema validation, origin policy,
+subprotocol selection, and message limits.
+
+Use `TestHost.create(app)` for the full app-host behavior, including JSON
+validation, heartbeat, idle timeout, and queue limits. Native `sloppy run`
+supports HTTP/1.1 Upgrade plus text and binary frame delivery for the same
+route, but does not model the full TestHost helper surface.

package/examples/websocket-echo/app.js

@@ -0,0 +1,36 @@
+import { Sloppy, schema } from "sloppy";
+
+const app = Sloppy.create();
+
+const ClientMessage = schema.object({
+    type: schema.enum(["ping", "echo"]),
+    text: schema.string().optional(),
+});
+
+app.websocket("/ws", async (socket) => {
+    await socket.accept();
+
+    for await (const message of socket.messages()) {
+        if (message.kind === "text") {
+            await socket.sendText(`echo:${message.text}`);
+            continue;
+        }
+        if (message.kind === "json") {
+            const input = message.validate(ClientMessage);
+            if (input.type === "ping") {
+                await socket.sendJson({ type: "pong" });
+            } else {
+                await socket.sendJson({ type: "echo", text: input.text ?? "" });
+            }
+        }
+    }
+}, {
+    origins: ["https://app.example.com"],
+    protocols: ["sloppy.realtime"],
+    maxMessageBytes: 64 * 1024,
+    maxSendQueueBytes: 1024 * 1024,
+    heartbeatMs: 15_000,
+    idleTimeoutMs: 30_000,
+});
+
+export default app;

package/examples/websocket-json-schema/README.md

@@ -0,0 +1,5 @@
+# WebSocket JSON Schema
+
+Schema-validated JSON WebSocket messages for app-host tests. Invalid messages
+fail through the handler error path and close the socket with an internal-error
+close code.

package/examples/websocket-json-schema/app.js

@@ -0,0 +1,25 @@
+import { Sloppy, schema } from "sloppy";
+
+const app = Sloppy.create();
+
+const ClientMessage = schema.object({
+    type: schema.enum(["ping", "echo"]),
+    text: schema.string().optional(),
+});
+
+app.websocket("/json", async (socket) => {
+    await socket.accept();
+
+    for await (const message of socket.messages()) {
+        const input = message.validate(ClientMessage);
+        if (input.type === "ping") {
+            await socket.sendJson({ type: "pong" });
+        } else {
+            await socket.sendJson({ type: "echo", text: input.text ?? "" });
+        }
+    }
+}, {
+    maxMessageBytes: 64 * 1024,
+});
+
+export default app;

package/examples/websocket-testhost/README.md

@@ -0,0 +1,11 @@
+# WebSocket TestHost
+
+Plain JavaScript TestHost example for the WebSocket echo app.
+
+```powershell
+node examples/websocket-testhost/test.mjs
+```
+
+The test uses the app-host lane. Artifact, package, and loopback TestHost lanes
+report `SLOPPY_E_TESTHOST_WEBSOCKET_UNSUPPORTED` unless a supplied runtime host
+implements `websocketConnect`.

package/examples/websocket-testhost/test.mjs

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+
+import { Sloppy, TestHost, schema } from "sloppy";
+
+const app = Sloppy.create();
+
+const ClientMessage = schema.object({
+    type: schema.enum(["ping", "echo"]),
+    text: schema.string().optional(),
+});
+
+app.websocket("/ws", async (socket) => {
+    await socket.accept();
+
+    for await (const message of socket.messages()) {
+        if (message.kind === "text") {
+            await socket.sendText(`echo:${message.text}`);
+            continue;
+        }
+        if (message.kind === "json") {
+            const input = message.validate(ClientMessage);
+            if (input.type === "ping") {
+                await socket.sendJson({ type: "pong" });
+            }
+        }
+    }
+}, {
+    origins: ["https://app.example.com"],
+    protocols: ["sloppy.realtime"],
+});
+
+const host = await TestHost.create(app);
+
+try {
+    const ws = await host.websocket("/ws")
+        .origin("https://app.example.com")
+        .protocols(["sloppy.realtime"])
+        .connect();
+
+    assert.equal(ws.protocol, "sloppy.realtime");
+
+    await ws.sendText("hello");
+    await ws.expectText("echo:hello");
+    await ws.sendJson({ type: "ping" });
+    await ws.expectJson({ type: "pong" });
+    await ws.close();
+} finally {
+    await host.close();
+}

package/examples/workers-background-service/README.md

@@ -0,0 +1,7 @@
+# Workers Background Service
+
+This example shows a lifecycle-bound background service shape.
+
+Shows a lifecycle-bound `BackgroundService` registered with `app.use(...)`.
+
+The service uses a cancellation-aware loop and avoids logging payload data.

package/examples/workers-background-service/app.js

@@ -0,0 +1,16 @@
+import { Sloppy, Results } from "sloppy";
+import { Time } from "sloppy/time";
+import { BackgroundService } from "sloppy/workers";
+
+const app = Sloppy.create();
+
+const cleanup = BackgroundService.create("cleanup", async (ctx) => {
+  while (!ctx.signal.cancelled) {
+    await Time.delay(5 * 60 * 1000, { signal: ctx.signal });
+  }
+});
+
+app.use(cleanup);
+app.mapGet("/", () => Results.text("worker service registered"));
+
+export default app;

package/examples/workers-js-isolate/README.md

@@ -0,0 +1,8 @@
+# Workers JS Isolate
+
+This is a V8-enabled worker API example.
+
+Shows the explicit `Worker.start(...).invoke(...).stop()` API shape.
+
+With V8 enabled, the worker module is loaded as Sloppy-owned source, invoked in
+a worker-owned isolate, and settled back on the app isolate owner thread.

package/examples/workers-js-isolate/app.js

@@ -0,0 +1,19 @@
+import { Sloppy, Results } from "sloppy";
+import { Deadline } from "sloppy/time";
+import { Worker } from "sloppy/workers";
+
+const app = Sloppy.create();
+
+app.mapPost("/parse", async () => {
+  const worker = await Worker.start("./workers/parser.ts", { memoryLimitMb: 128 });
+  try {
+    const parsed = await worker.invoke("parse", { text: "one two three" }, {
+      deadline: Deadline.after(1000),
+    });
+    return Results.json(parsed);
+  } finally {
+    await worker.stop();
+  }
+});
+
+export default app;

package/examples/workers-js-isolate/workers/parser.ts

@@ -0,0 +1,11 @@
+export async function parse(payload) {
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new TypeError("parse payload must be an object.");
+  }
+  if (typeof payload.text !== "string") {
+    throw new TypeError("parse payload text must be a string.");
+  }
+  return {
+    tokens: payload.text.split(/\s+/u).filter(Boolean).length,
+  };
+}

package/examples/workers-shutdown/README.md

@@ -0,0 +1,6 @@
+# Workers Shutdown
+
+This example shows worker shutdown behavior for queue draining.
+
+Shows explicit queue drain behavior. `stop({ drain: true })` rejects new admission and waits
+for already admitted work to settle.

package/examples/workers-shutdown/app.js

@@ -0,0 +1,26 @@
+import { Sloppy, Results } from "sloppy";
+import { WorkQueue } from "sloppy/workers";
+
+const app = Sloppy.create();
+
+const queue = WorkQueue.create("shutdown-demo", {
+  maxQueued: 8,
+  concurrency: 1,
+  overflow: "reject",
+});
+
+queue.process(async (job, ctx) => {
+  if (ctx.signal.cancelled) {
+    return { skipped: true };
+  }
+  return { handled: job.data.id };
+});
+
+app.use(queue);
+app.mapPost("/jobs", async () => {
+  await queue.enqueue({ id: 1 });
+  await queue.stop({ drain: true });
+  return Results.accepted({ drained: true });
+});
+
+export default app;