@venn-lang/http 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# @venn-lang/http
+
+> The `http` namespace: seven request verbs, a server, and the two ports they ride.
+
+Venn's grammar knows no verbs. `@venn-lang/http` registers the `http` namespace with the runtime, so
+`http.get` resolves to an action, `res` gets a known shape, and the editor can complete and document
+both. The plugin itself never touches the network: requests go through the `HttpClient` port and
+servers through the `HttpServer` port, so the CLI binds `fetch` and a real socket while a test binds
+a fake and stays offline.
+
+## Install
+
+Nothing to install yet. The package is unpublished (version `0.0.0`) and ships inside
+`@venn-lang/stdlib`, which the `venn` CLI and the language server both load. A `.vn` file declares it:
+
+```ruby
+use "venn/http"
+```
+
+## Usage
+
+```ruby
+module demo.api
+
+use "venn/http"
+use "venn/assert"
+
+config { baseUrl: "https://api.test" }
+
+flow "Health" {
+  step "the service answers" {
+    const res = http.get "/health"
+    expect res.status == 200
+    expect res.ok
+    expect res header "content-type"
+  }
+}
+```
+
+A relative path is joined onto `config.baseUrl`; a URL with a scheme passes through untouched.
+
+## API
+
+Everything below is exported from the package barrel.
+
+| Export | What it is |
+| --- | --- |
+| `httpPlugin` (also the default export) | The `PluginDefinition`: namespace `http`, `requires: ["net"]`. |
+| `HttpClientPort` | `Port<HttpClient>`, id `venn.port.http-client`, version 1, method `request`. |
+| `createFetchClient()` | The real client, backed by the global `fetch`. |
+| `createFakeClient({ responses })` | The double: canned responses keyed by URL, `okResponse()` for anything else. |
+| `okResponse(overrides?)` | A `200` response with body `{"ok":true}`, for seeding the fake. |
+| `HttpServerPort` | `Port<HttpServer>`, id `venn.port.http-server`, version 1, method `listen`. |
+| `createMemoryServer()` | The double: no socket, and `deliver(request)` to knock on its door. |
+| `serveAction()`, `onAction()` | The two `ActionDefinition`s behind `http.serve` and `http.on`. |
+| `portInUse`, `listenFailed`, `asListenError` | `VennError` producers for `VN7020` and `VN7021`. |
+
+Types: `HttpClient`, `HttpRequest`, `HttpResponse`, `HttpServer`, `RequestHandler`, `RunningServer`,
+`ServerRequest`, `ServerReply`, `ServeHandle`, `MemoryServer`, `MemoryHttpServer`.
+
+The subpath `@venn-lang/http/node` carries the one file that imports `node:*`:
+
+```ts
+import { createNodeServer, type NodeHttpServer } from "@venn-lang/http/node";
+```
+
+`createNodeServer()` binds a real socket and adds `closeAll()`, so whoever owns the process can give
+its sockets back on the way out. Keeping it behind a subpath is what lets the main entry stay neutral
+and run in the editor's worker.
+
+## Verbs
+
+| Verb | Shape | Result |
+| --- | --- | --- |
+| `http.get` `http.post` `http.put` `http.patch` `http.delete` `http.head` `http.options` | `http.get url { … }` | `http.Response` |
+| `http.serve` | `http.serve { port, host }` | `http.Server` |
+| `http.on` | `http.on(server, handler)` | nothing |
+
+Every request verb takes the URL as its one positional argument. The rest is the trailing options map:
+
+| Option | Meaning |
+| --- | --- |
+| `headers` | Extra headers. Anything set here wins over what Venn would infer. |
+| `query` | Appended to the URL as a query string, encoded for you. |
+| `body` | What to send. A map becomes JSON; a string is sent as written. |
+| `encode` | `json`, `form`, `multipart` or `raw`. Defaults to `json` for a map, `raw` for a string. |
+| `bearer` | Shorthand for `Authorization: Bearer …`. |
+| `basic` | `{ user, pass }`, as HTTP basic auth. |
+
+`http.serve` takes `port` (`0` asks for any free one) and `host` (defaults to `127.0.0.1`).
+
+## Serving
+
+A server is not a request-response verb: it stays, and the requests arrive afterwards. So `http.serve`
+hands back a handle, and `http.on` says what to answer with.
+
+```ruby
+use "venn/http"
+
+const api = http.serve { port: 0 }
+defer { api.close() }
+
+http.on(api, route)
+
+fn route(req) {
+  const path = req.url.before("?")
+  path == "/health" ? { ok: true, method: req.method } : { status: 404 }
+}
+
+print "listening on http://127.0.0.1:${api.port}"
+```
+
+The handler is an ordinary `fn`, so everything the language does works inside it. A map carrying
+`status`, `headers` or `body` is taken as a reply; anything else becomes the body of a `200`;
+returning nothing sends `204`. Until `http.on` runs, the server answers `404`, so a request that
+arrives early gets an answer instead of hanging.
+
+## Matchers and types
+
+`header` is the one matcher: `expect res header "content-type"` passes when the response carries that
+header. It declares an optional second argument for the expected value, but the check today is
+presence only.
+
+The plugin publishes four types to the checker: `http.Response` (`status`, `ok`, `headers`, `body`
+as raw text, `json` as that text parsed, `time`), `http.Request`, `http.Reply` and `http.Server`.
+`json` is the one field nothing can know the shape of, so give it one by naming it:
+`const price: Price = res.json`.
+
+## Ports and conformance
+
+Two ports, each with two implementations and a suite both must pass:
+
+- `HttpClient`: `createFetchClient` and `createFakeClient`, checked by
+  `src/clients/http-client.suite.ts`. The test stubs the global `fetch` so the real client's mapping
+  runs the same suite offline.
+- `HttpServer`: `createNodeServer` and `createMemoryServer`, checked by
+  `src/server/http-server.suite.ts`. The double keeps its own book of bound ports, so a flow that
+  binds the same port twice fails there exactly as it would against a real socket.
+
+Binding one implementation looks like this:
+
+```ts
+import { createFakeClient, HttpClientPort, okResponse } from "@venn-lang/http";
+
+const ports = [
+  {
+    port: HttpClientPort,
+    impl: createFakeClient({
+      responses: { "https://api.test/health": okResponse({ status: 200 }) },
+    }),
+  },
+];
+```
+
+A socket that refuses to bind is translated at the producer: `EADDRINUSE` becomes `VN7020`, anything
+else `VN7021`. No caller ever reads a `node:net` errno.
+
+## See also
+
+- [`@venn-lang/sdk`](../sdk) for `definePlugin`, `defineAction` and `defineMatcher`.
+- [`@venn-lang/stdlib`](../stdlib) for the plugin list and the default port bindings.
+- [`@venn-lang/ws`](../std-ws) and [`@venn-lang/mqtt`](../std-mqtt), the other two network plugins.

package/dist/index.d.ts

@@ -0,0 +1,213 @@
+import { ActionDefinition, PluginDefinition } from "@venn-lang/sdk";
+import { Port, VennError } from "@venn-lang/contracts";
+//#region src/port/http-client.types.d.ts
+/** One request, ready to send: the verb, the absolute URL and the payload. */
+interface HttpRequest {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: string;
+  /** Aborted when a `race` this request runs inside has already been won. */
+  signal?: AbortSignal;
+}
+/** What an http verb hands back, and what `res` holds in a flow. */
+interface HttpResponse {
+  status: number;
+  ok: boolean;
+  headers: Record<string, string>;
+  body: string;
+  json: unknown;
+  time: number;
+}
+/**
+ * Sending one request and reading the reply.
+ *
+ * Two implementations: `createFetchClient` over a real socket and
+ * `createFakeClient` for tests. The conformance suite is what says they agree.
+ */
+interface HttpClient {
+  request(req: HttpRequest): Promise<HttpResponse>;
+}
+//#endregion
+//#region src/port/http-client.port.d.ts
+/**
+ * The port descriptor an http verb resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot open sockets refuses the
+ * binding at load time with a readable diagnostic.
+ */
+declare const HttpClientPort: Port<HttpClient>;
+//#endregion
+//#region src/clients/fake-client.d.ts
+/**
+ * A 200 response with a small JSON body, for tests that only care about a field
+ * or two.
+ *
+ * @param overrides Fields to replace on the default response.
+ * @returns A complete {@link HttpResponse}.
+ */
+declare function okResponse(overrides?: Partial<HttpResponse>): HttpResponse;
+/**
+ * The double: answers from a table keyed by the request's full URL.
+ *
+ * A URL with no entry gets {@link okResponse}, so a test only has to name the
+ * responses it cares about. Never touches the network.
+ *
+ * @param args.responses Canned responses, keyed by the URL the flow requests.
+ */
+declare function createFakeClient(args?: {
+  responses?: Record<string, HttpResponse>;
+}): HttpClient;
+//#endregion
+//#region src/clients/fetch-client.d.ts
+/**
+ * The real client, over the global `fetch`. Requires the `net` capability.
+ *
+ * The body is always read as text and parsed afterwards, so a reply that claims
+ * JSON but is not still arrives whole in `body` instead of throwing.
+ */
+declare function createFetchClient(): HttpClient;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `http` namespace: the request verbs, `http.serve`/`http.on`, the `header`
+ * matcher and the types they trade in.
+ *
+ * Requires the `net` capability, so a host without it refuses the plugin at load
+ * time rather than failing mid-flow. The compiler treats it exactly as it treats
+ * a third-party plugin.
+ */
+declare const httpPlugin: PluginDefinition;
+//#endregion
+//#region src/server/http-server.errors.d.ts
+/** VN7020: the address the flow asked for is already taken by something else. */
+declare function portInUse(args: {
+  port: number;
+  host: string;
+}): VennError;
+/** VN7021: the socket refused to bind for any other reason. */
+declare function listenFailed(args: {
+  port: number;
+  host: string;
+  cause: string;
+}): VennError;
+/**
+ * Whatever the socket threw, as a Venn error: VN7020 for `EADDRINUSE`, VN7021
+ * for anything else.
+ *
+ * The translation lives at the producer so no caller has to read a `node:net`
+ * errno to know what went wrong.
+ */
+declare function asListenError(args: {
+  port: number;
+  host: string;
+  error: unknown;
+}): VennError;
+//#endregion
+//#region src/server/http-server.types.d.ts
+/** One request a server received, as the language sees it. */
+interface ServerRequest {
+  method: string;
+  /** The path with its query string, exactly as it arrived. */
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+}
+/** What a handler answers with. Every field has a sensible default. */
+interface ServerReply {
+  status?: number;
+  headers?: Record<string, string>;
+  /** A string is sent as-is; anything else is sent as JSON. */
+  body?: unknown;
+}
+/** Called once per request. Returning nothing sends `204 No Content`. */
+type RequestHandler = (request: ServerRequest) => ServerReply | undefined | Promise<ServerReply | undefined>;
+/** A server that is listening, and how to stop it. */
+interface RunningServer {
+  /** The port it actually bound to. Asking for 0 gets one chosen for you. */
+  readonly port: number;
+  close(): Promise<void>;
+}
+/**
+ * Accepting requests over HTTP.
+ *
+ * Two implementations: `createNodeServer` binds a real socket, and
+ * `createMemoryServer` keeps the handler in memory so a test can deliver a
+ * request without a network. The conformance suite is what says they agree.
+ */
+interface HttpServer {
+  listen(args: {
+    port: number;
+    host?: string;
+    handle: RequestHandler;
+  }): Promise<RunningServer>;
+}
+//#endregion
+//#region src/server/http-server.port.d.ts
+/**
+ * The port descriptor `http.serve` resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot bind a socket refuses the
+ * binding at load time rather than mid-flow.
+ */
+declare const HttpServerPort: Port<HttpServer>;
+//#endregion
+//#region src/server/memory-server.d.ts
+/** A server that is listening in memory, plus the way to knock on its door. */
+interface MemoryServer extends RunningServer {
+  /** Deliver a request as though it had arrived over the network. */
+  deliver(request: Partial<ServerRequest>): Promise<ServerReply>;
+  readonly closed: boolean;
+}
+/** The double factory, which keeps every server it started so a test can find it. */
+interface MemoryHttpServer extends HttpServer {
+  /** Every server started through this, newest last. */
+  readonly started: readonly MemoryServer[];
+}
+/**
+ * The double: no socket, no network, no waiting.
+ *
+ * A test starts the flow that serves, hands it a request and reads the reply,
+ * running the same handler the real server would call. Ports are book-kept here
+ * rather than by the operating system, so tests beside each other never collide.
+ */
+declare function createMemoryServer(): MemoryHttpServer;
+//#endregion
+//#region src/server/on-action.d.ts
+/**
+ * `http.on server handler`: say what the server answers with.
+ *
+ * The handler is an ordinary `fn`, so everything the language already does
+ * applies inside it: it can call any verb, and it waits for what it reaches for
+ * without saying so. Whatever it returns becomes the reply. Calling `http.on`
+ * again replaces the handler.
+ */
+declare function onAction(): ActionDefinition;
+//#endregion
+//#region src/server/serve-action.d.ts
+/**
+ * The value `http.serve` hands back, seen by flows as `http.Server`.
+ *
+ * A server is not a request-response verb: it stays, and the requests arrive
+ * afterwards. So the verb returns something the program holds on to: the port it
+ * got, and what it may do with it.
+ */
+interface ServeHandle {
+  kind: "http-server";
+  port: number;
+  /** Deliver one request to whatever `handle` was last given. Used by tests. */
+  deliver: (request: Partial<ServerRequest>) => Promise<ServerReply>;
+  close: () => Promise<void>;
+  /** Replace the handler. `http.on` is how a flow reaches this. */
+  onRequest: (handle: (request: ServerRequest) => unknown) => void;
+}
+/**
+ * `let api = http.serve { port: 8080 }`: start listening.
+ *
+ * The handler starts as a 404 and `http.on` replaces it, so a request arriving
+ * before the flow has said what to do with it gets an answer instead of hanging.
+ */
+declare function serveAction(): ActionDefinition;
+//#endregion
+export { type HttpClient, HttpClientPort, type HttpRequest, type HttpResponse, type HttpServer, HttpServerPort, type MemoryHttpServer, type MemoryServer, type RequestHandler, type RunningServer, type ServeHandle, type ServerReply, type ServerRequest, asListenError, createFakeClient, createFetchClient, createMemoryServer, httpPlugin as default, httpPlugin, listenFailed, okResponse, onAction, portInUse, serveAction };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/port/http-client.types.ts","../src/port/http-client.port.ts","../src/clients/fake-client.ts","../src/clients/fetch-client.ts","../src/plugin.ts","../src/server/http-server.errors.ts","../src/server/http-server.types.ts","../src/server/http-server.port.ts","../src/server/memory-server.ts","../src/server/on-action.ts","../src/server/serve-action.ts"],"mappings":";;;;UACiB;EACf;EACA;EACA,UAAU;EACV;;EAEA,SAAS;;;UAIM;EACf;EACA;EACA,SAAS;EACT;EACA;EACA;;;;;;;;UASe;EACf,QAAQ,KAAK,cAAc,QAAQ;;;;;;;;;;cClBxB,gBAAgB,KAAK;;;;;;;;;;iBCAlB,WAAW,YAAW,QAAQ,gBAAqB;;;;;;;;;iBAoBnD,iBACd;EAAQ,YAAY,eAAe;IAClC;;;;;;;;;iBCvBa,qBAAqB;;;;;;;;;;;cCKxB,YAAY;;;;iBCVT,UAAU;EAAQ;EAAc;IAAiB;;iBASjD,aAAa;EAAQ;EAAc;EAAc;IAAkB;;;;;;;;iBAenE,cAAc;EAAQ;EAAc;EAAc;IAAmB;;;;UC1BpE;EACf;;EAEA;EACA,SAAS;EACT;;;UAIe;EACf;EACA,UAAU;;EAEV;;;KAIU,kBACV,SAAS,kBACN,0BAA0B,QAAQ;;UAGtB;;WAEN;EACT,SAAS;;;;;;;;;UAUM;EACf,OAAO;IAAQ;IAAc;IAAe,QAAQ;MAAmB,QAAQ;;;;;;;;;;cC5BpE,gBAAgB,KAAK;;;;UCIjB,qBAAqB;;EAEpC,QAAQ,SAAS,QAAQ,iBAAiB,QAAQ;WACzC;;;UAIM,yBAAyB;;WAE/B,kBAAkB;;;;;;;;;iBAUb,sBAAsB;;;;;;;;;;;iBCpBtB,YAAY;;;;;;;;;;UCKX;EACf;EACA;;EAEA,UAAU,SAAS,QAAQ,mBAAmB,QAAQ;EACtD,aAAa;;EAEb,YAAY,SAAS,SAAS;;;;;;;;iBAShB,eAAe"}