@gjermundgaraba/effect-actions 0.11.0 → 0.12.0

package/examples/notes-service/test/notes/notes.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Array, Effect, Exit, References } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentUser } from "../../src/identity/Identity.js";
+import { users } from "../../src/identity/users.js";
+import { notes } from "../../src/notes/handlers.js";
+import { NoteChanged, NoteNotFound } from "../../src/notes/Notes.js";
+import { NoteStore } from "../../src/notes/store.js";
+
+// What the implementation does, with no transport: `Action.client` runs the same decoding,
+// `authorize` and handler a server runs. Each call names its caller, as a request would.
+const as = (user: keyof typeof users) => Effect.provideService(CurrentUser, users[user]);
+
+describe("notes, in process", () => {
+  it.effect("keeps each user's notes their own", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
+
+      expect(yield* client.listNotes().pipe(as("ada"))).toEqual({
+        notes: [{ id: note.id, title: "Plan" }],
+      });
+      expect(yield* client.listNotes().pipe(as("grace"))).toEqual({ notes: [] });
+
+      const missing = new NoteNotFound({ id: note.id });
+      const update = { id: note.id, body: "Mine now", revision: note.revision };
+
+      expect(yield* Effect.flip(client.getNote({ id: note.id }).pipe(as("grace")))).toEqual(
+        missing,
+      );
+      expect(yield* Effect.flip(client.updateNote(update).pipe(as("grace")))).toEqual(missing);
+      expect(yield* Effect.flip(client.deleteNote({ id: note.id }).pipe(as("grace")))).toEqual(
+        missing,
+      );
+      expect(yield* client.getNote({ id: note.id }).pipe(as("ada"))).toEqual(note);
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+
+  it.effect("deletes a note for its owner", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
+
+      yield* client.deleteNote({ id: note.id }).pipe(as("ada"));
+
+      expect(yield* Effect.flip(client.getNote({ id: note.id }).pipe(as("ada")))).toEqual(
+        new NoteNotFound({ id: note.id }),
+      );
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+
+  it.effect("refuses an update of a revision that is no longer current", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
+      const update = { id: note.id, body: "Final", revision: note.revision };
+
+      expect(yield* client.updateNote(update).pipe(as("ada"))).toMatchObject({ revision: 2 });
+      expect(yield* Effect.flip(client.updateNote(update).pipe(as("ada")))).toEqual(
+        new NoteChanged({ id: note.id, revision: 2 }),
+      );
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+
+  it.effect("lets one of two concurrent updates of the same revision through", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+
+      // A fiber is set aside after every `steps` steps, and two that run at once then take
+      // turns. Each count sets the first update aside at another point of its work; under
+      // three, the two do not finish.
+      const succeeded = yield* Effect.forEach(Array.range(3, 60), (steps) =>
+        Effect.gen(function* () {
+          const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
+
+          const update = (body: string) =>
+            Effect.exit(client.updateNote({ id: note.id, body, revision: 1 }).pipe(as("ada")));
+
+          const exits = yield* Effect.all([update("One"), update("Two")], {
+            concurrency: "unbounded",
+          }).pipe(Effect.provideService(References.MaxOpsBeforeYield, steps));
+
+          return exits.filter(Exit.isSuccess).length;
+        }),
+      );
+
+      expect(succeeded).toEqual(Array.range(3, 60).map(() => 1));
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+
+  it.effect("refuses a write from a caller holding the read scope alone", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const create = client.createNote({ title: "Plan", body: "Draft" });
+      const refusal = yield* Effect.flip(create.pipe(as("reader")));
+
+      // `toEqual` on an error compares its fields and never its message, so the message is
+      // asserted on its own.
+      expect(refusal).toBeInstanceOf(Action.Forbidden);
+      expect(refusal.message).toBe("Requires notes:write.");
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+});

package/examples/notes-service/test/routes.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Http } from "../src/Api.js";
+import { Notes } from "../src/notes/Notes.js";
+import { NoteStore } from "../src/notes/store.js";
+import { routes } from "../src/routes.js";
+import { GetStatus } from "../src/status/Status.js";
+
+// What the wire adds: the real routes, behind their real authentication, answering in memory.
+// No port is opened. The caller is the token each client sends, as in production.
+const served = Testing.layer(routes).pipe(Layer.provide(NoteStore.layerMemory));
+
+const as = (token: string) => ({
+  transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
+});
+
+describe("the service, over HTTP and MCP", () => {
+  it.effect("answers the public action without a token and refuses the rest", () =>
+    Effect.gen(function* () {
+      const anyone = yield* ActionHttp.client(Http);
+
+      expect(yield* anyone.getStatus()).toEqual({ service: "notes-service", notes: 0 });
+      expect(yield* Effect.flip(anyone.whoAmI())).toBeInstanceOf(Action.Unauthenticated);
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("refuses a token no user holds", () =>
+    Effect.gen(function* () {
+      const stranger = yield* ActionHttp.client(Http, as("mallory"));
+
+      const refusal = yield* Effect.flip(stranger.whoAmI());
+
+      expect(refusal).toBeInstanceOf(Action.Unauthenticated);
+      expect(refusal.message).toBe("Unknown demo token.");
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("serves the host's own routes beside the actions'", () =>
+    Effect.gen(function* () {
+      const health = yield* HttpClient.get("/healthz");
+      const openApi = yield* HttpClient.get("/api/openapi.json");
+
+      expect(yield* health.text).toBe("ok");
+      expect(yield* openApi.text).toContain('"/api/createNote"');
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("names the scope a caller lacks, so an OAuth client can ask for it", () =>
+    Effect.gen(function* () {
+      const reader = yield* ActionHttp.client(Http, as("reader"));
+
+      expect(yield* reader.whoAmI()).toEqual({ id: "reader", scopes: ["notes:read"] });
+
+      const refusal = yield* Effect.flip(reader.createNote({ title: "Plan", body: "" }));
+
+      expect(refusal).toBeInstanceOf(Action.Forbidden);
+      expect(refusal).toHaveProperty("scopes", ["notes:write"]);
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("serves one store to both surfaces: a note written over HTTP is read as a tool", () =>
+    Effect.gen(function* () {
+      const http = yield* ActionHttp.client(Http, as("ada"));
+      const mcp = yield* Testing.mcpClient([GetStatus, ...Notes], as("ada"));
+      const note = yield* http.createNote({ title: "Plan", body: "Draft" });
+
+      expect(yield* mcp.getNote({ id: note.id })).toEqual(note);
+      expect(yield* mcp.getStatus()).toEqual({ service: "notes-service", notes: 1 });
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("lists every tool to a signed-out MCP client, as one of them is public", () =>
+    Effect.gen(function* () {
+      const response = yield* HttpClient.execute(Testing.mcpRequest("tools/list"));
+
+      expect(response.status).toBe(200);
+      expect(yield* response.text).toContain('"name":"createNote"');
+    }).pipe(Effect.provide(served)),
+  );
+});

package/examples/quickstart/README.md

@@ -0,0 +1,31 @@
+# quickstart
+
+The smallest complete program: one action, served as a JSON route and as an MCP tool, called
+with its typed client. It is the skeleton of [notes-service](../notes-service/), which adds
+authentication, authorization, declared errors, a store, a CLI and a browser client to the same
+layout.
+
+## Run it
+
+From the repository root, after `vp install` (from an installed package, see
+[Run one](../README.md#run-one)):
+
+```sh
+node --import tsx examples/quickstart/src/server.ts     # 127.0.0.1:3000
+node --import tsx examples/quickstart/src/client.ts     # Hello, Ada!
+vp test examples/quickstart
+```
+
+## Layout
+
+```text
+src/
+├── greeting/
+│   ├── Greeting.ts    the contract
+│   └── handlers.ts    its implementation
+├── Api.ts             the HTTP binding, shared by server and client
+├── routes.ts          the surfaces: POST /api/greet and /mcp
+├── server.ts          entrypoint
+└── client.ts          entrypoint
+test/greeting/         the routes, called in memory
+```

package/examples/quickstart/src/Api.ts

@@ -0,0 +1,5 @@
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Greet } from "./greeting/Greeting.js";
+
+// The HTTP binding: `POST /api/greet`. The server serves it and the client calls it.
+export const Http = ActionHttp.make([Greet]);

package/examples/quickstart/src/client.ts

@@ -0,0 +1,13 @@
+import { NodeRuntime } from "@effect/platform-node";
+import { Console, Effect } from "effect";
+import { FetchHttpClient } from "effect/http";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Http } from "./Api.js";
+
+// Entrypoint: `node --import tsx examples/quickstart/src/client.ts`, with the server running.
+// One typed method per action of the binding.
+Effect.gen(function* () {
+  const client = yield* ActionHttp.client(Http, { baseUrl: "http://127.0.0.1:3000" });
+
+  yield* Console.log(yield* client.greet({ name: "Ada" }));
+}).pipe(Effect.provide(FetchHttpClient.layer), NodeRuntime.runMain);

package/examples/quickstart/src/greeting/Greeting.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+
+// A contract: what the action takes and answers, whether it changes anything, and who may
+// call it. It imports no server code, so any client can import it, a browser page included.
+export const Greet = Action.make("greet", {
+  description: "Greet someone by name.",
+  input: { name: Schema.String },
+  success: Schema.String,
+  readOnly: true,
+  caller: Action.Anyone,
+});

package/examples/quickstart/src/greeting/handlers.ts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Greet } from "./Greeting.js";
+
+// The implementation: the contract bound to its handler. Every surface takes this one value.
+export const greeting = Action.implement(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));

package/examples/quickstart/src/routes.ts

@@ -0,0 +1,11 @@
+import { Layer } from "effect";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { Http } from "./Api.js";
+import { greeting } from "./greeting/handlers.js";
+
+// One implementation, two surfaces: a JSON route and an MCP tool at `/mcp`.
+export const routes = Layer.mergeAll(
+  ActionHttp.layer(Http, greeting),
+  ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" }),
+);

package/examples/quickstart/src/server.ts

@@ -0,0 +1,16 @@
+import { createServer } from "node:http";
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
+import { Layer } from "effect";
+import { HttpRouter } from "effect/http";
+import { routes } from "./routes.js";
+
+// Entrypoint: `node --import tsx examples/quickstart/src/server.ts`.
+// A real server reads its port from config, `Config.Port("PORT")`, and limits request bodies:
+// `Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1)))`.
+// `127.0.0.1` serves this machine alone: a server others reach reads its host from config,
+// `Config.String("HOST").pipe(Config.withDefault("127.0.0.1"))`.
+HttpRouter.serve(routes).pipe(
+  Layer.provide(NodeHttpServer.layer(createServer, { host: "127.0.0.1", port: 3000 })),
+  Layer.launch,
+  NodeRuntime.runMain,
+);

package/examples/quickstart/test/greeting/greeting.test.ts

@@ -0,0 +1,18 @@
+import { expect, it } from "@effect/vitest";
+import { Effect } from "effect";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Http } from "../../src/Api.js";
+import { Greet } from "../../src/greeting/Greeting.js";
+import { routes } from "../../src/routes.js";
+
+// The routes answer in memory: no port, and the same code the server runs.
+it.effect("greets over HTTP and as an MCP tool", () =>
+  Effect.gen(function* () {
+    const http = yield* ActionHttp.client(Http);
+    const mcp = yield* Testing.mcpClient([Greet]);
+
+    expect(yield* http.greet({ name: "Ada" })).toBe("Hello, Ada!");
+    expect(yield* mcp.greet({ name: "Ada" })).toBe("Hello, Ada!");
+  }).pipe(Effect.provide(Testing.layer(routes))),
+);

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.11.0",
-  "description": "Define Effect action contracts once and project them onto HTTP, MCP, native Toolkits, and CLIs.",
+  "version": "0.12.0",
+  "description": "Define Effect action contracts once and project them onto HTTP, MCP, Effect RPC, native Toolkits, and CLIs.",
+  "keywords": [
+    "ai-agents",
+    "cli",
+    "effect",
+    "effect-ts",
+    "http-api",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "rpc",
+    "typescript"
+  ],
   "homepage": "https://github.com/gjermundgaraba/effect-actions#readme",
   "bugs": {
     "url": "https://github.com/gjermundgaraba/effect-actions/issues"
@@ -11,9 +23,14 @@
     "type": "git",
     "url": "git+https://github.com/gjermundgaraba/effect-actions.git"
   },
+  "directories": {
+    "doc": "docs",
+    "example": "examples"
+  },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "examples"
   ],
   "type": "module",
   "sideEffects": false,
@@ -22,6 +39,7 @@
     "./ActionCli": "./dist/ActionCli.mjs",
     "./ActionHttp": "./dist/ActionHttp.mjs",
     "./ActionMcp": "./dist/ActionMcp.mjs",
+    "./ActionRpc": "./dist/ActionRpc.mjs",
     "./ActionToolkit": "./dist/ActionToolkit.mjs",
     "./Authentication": "./dist/Authentication.mjs",
     "./Testing": "./dist/Testing.mjs",
@@ -65,8 +83,8 @@
     "dev": "vp pack --watch",
     "test": "vp test",
     "check": "vp check",
-    "example": "node --import tsx examples/server.ts",
-    "test:package": "vp run build && node scripts/test-package.mjs",
+    "example": "node --import tsx examples/notes-service/src/server.ts",
+    "test:package": "vp run build && node --import tsx scripts/test-package.ts",
     "docs:sync": "node --import tsx scripts/sync-skill.ts"
   }
 }

package/dist/internal/actions.d.mts

@@ -1,9 +0,0 @@
-import "../Action.mjs";
-import { SchemaAST } from "effect";
-//#region src/internal/actions.d.ts
-/**
- * The caller of a public action: anyone, signed in or not. Registered globally, so two copies
- * of the package agree on it, as they agree on a name.
- */
-export declare const Anyone: unique symbol;
-//#endregion

package/dist/internal/authentication.mjs

@@ -1,11 +0,0 @@
-import { Unauthenticated } from "./errors.mjs";
-import { Anyone } from "./actions.mjs";
-import { Effect, Option } from "effect";
-//#region src/internal/authentication.ts
-const assertAuthentication = (actions, auth) => {
-	for (const action of actions) if (action.caller !== Anyone && (auth === void 0 || action.caller.key !== auth.identity.key)) throw new Error(`Protected action '${action.name}' requires its matching authentication descriptor`);
-};
-/** Remote promotion happens at tool entry, before shared dispatch, never in local calls. */
-const promote = (auth, run) => Effect.flatMap(Effect.serviceOption(auth["~verified"]), (actor) => Option.isSome(actor) ? Effect.provideService(run, auth.identity, actor.value) : Effect.fail(new Unauthenticated()));
-//#endregion
-export { assertAuthentication, promote };

package/dist/internal/call.mjs

@@ -1,12 +0,0 @@
-import { Effect, Schema } from "effect";
-//#region src/internal/call.ts
-/**
-* The input a method of `action` sends for the arguments it was called with: a given
-* argument as given, and none as the input `{}` decodes to, as a server decodes the `{}` it
-* receives. `Call` allows none only when `{}` is a valid encoded input, which is what this
-* decodes; decoding makes it one of the input's own values, such as an instance of an input
-* class, or fills its defaults.
-*/
-const inputOf = (action, args) => args.length === 0 ? Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))({}) : Effect.succeed(args[0]);
-//#endregion
-export { inputOf };