@venn-lang/grpc 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,120 @@
+# @venn-lang/grpc
+
+> The `grpc` namespace: unary calls, server streams and server reflection as Venn verbs.
+
+Three verbs over one port. The method name is the positional argument and the request message is the
+options map, so a call reads the way a `.proto` does. This package never parses a `.proto` itself:
+what a call returns is `dynamic`, and reflection is the only shape it can describe.
+
+## Install
+
+The package ships with the stdlib, so the CLI already loads it. Inside a `.vn` file, bring the
+namespace in with `use`:
+
+```ruby
+use "venn/grpc"
+```
+
+## Usage
+
+```ruby
+module demo.inventory
+
+use "venn/grpc"
+
+flow "Inventory" {
+  step "check the stock" {
+    let res = grpc.call "Inventory/Check" { sku: "sku-42" }
+    expect res.inStock == true
+  }
+
+  step "watch the prices" {
+    let ticks = grpc.stream "Prices/Watch" { sku: "sku-42" }
+    expect ticks.len > 0
+  }
+}
+```
+
+The request message is a free-form map, so no key is ever "unknown" and `VN3001` cannot fire here.
+The trade is that nothing checks the field names either: they are the server's business.
+
+## Verbs
+
+| Verb | Positional argument | Options | Result |
+| --- | --- | --- | --- |
+| `grpc.call` | `method: string`, the full `package.Service/Method` | the request message | `dynamic` |
+| `grpc.stream` | `method: string` | the request message | `list<dynamic>` |
+| `grpc.reflect` | `service: string` | none | `list<grpc.MethodInfo>` |
+
+`grpc.stream` hands back the messages already collected into a list. It is not a live stream, so a
+flow reads it like any other list.
+
+## Types
+
+The plugin publishes one named type, the only thing it can honestly describe:
+
+| Name | Shape |
+| --- | --- |
+| `grpc.MethodInfo` | `{ name: string, requestType: string, responseType: string, clientStreaming: bool, serverStreaming: bool }` |
+
+A call's request and response come from a `.proto` nobody here has read, so they stay `dynamic`.
+
+## The GrpcClient port
+
+| | |
+| --- | --- |
+| id | `venn.port.grpc-client` |
+| version | `1` |
+| requires | `net` |
+| methods | `call`, `stream`, `reflect` |
+
+Two implementations ship with the package. `createFakeClient` replays canned messages keyed by
+method; `createRealClient` is a placeholder that throws `VN8090` on every call, since proto loading,
+channels and real reflection are out of scope for this build. The conformance suite lives in
+`src/clients/grpc-client.suite.ts` and the fake runs it today; the real client joins it the day it
+answers instead of throwing.
+
+`@venn-lang/stdlib` binds `createFakeClient()` with no configuration, so out of the box `call` answers
+`{}`, `stream` answers `[]` and `reflect` answers `[]`. To make the example above pass, bind a fake
+of your own:
+
+```ts
+import { createFakeClient, GrpcClientPort } from "@venn-lang/grpc";
+
+const binding = {
+  port: GrpcClientPort,
+  impl: createFakeClient({
+    responses: { "Inventory/Check": { inStock: true, quantity: 42 } },
+    streams: { "Prices/Watch": [{ price: 1 }, { price: 2 }] },
+    reflection: {
+      Inventory: [
+        {
+          name: "Check",
+          requestType: "CheckRequest",
+          responseType: "CheckResponse",
+          clientStreaming: false,
+          serverStreaming: false,
+        },
+      ],
+    },
+  }),
+};
+```
+
+`responses` and `streams` are keyed by the full method; `reflection` is keyed by service name.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `grpcPlugin` (also the default export) | The `PluginDefinition`: namespace `grpc`, `requires: ["net"]`, three actions. |
+| `GrpcClientPort` | The port descriptor actions resolve through `ctx.port(...)`. |
+| `createFakeClient({ responses?, streams?, reflection? })` | The test double. Unknown keys fall back to `{}` or `[]`. |
+| `createRealClient()` | The real client's slot. Every method throws `VN8090`. |
+| `GrpcCall`, `GrpcClient`, `GrpcMethodInfo` | Types only. |
+
+## See also
+
+- [`@venn-lang/graphql`](../std-graphql), the same port pattern over GraphQL.
+- [`@venn-lang/http`](../std-http), the HTTP verbs and the `Response` type.
+- [`@venn-lang/sdk`](../sdk), `defineAction` / `definePlugin`.

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { Port } from "@venn-lang/contracts";
+import { PluginDefinition } from "@venn-lang/sdk";
+//#region src/port/grpc-client.types.d.ts
+/** One invocation: the full `package.Service/Method`, plus the request message. */
+interface GrpcCall {
+  method: string;
+  request?: Record<string, unknown>;
+}
+/** Metadata for one RPC method, as returned by server reflection. */
+interface GrpcMethodInfo {
+  name: string;
+  requestType: string;
+  responseType: string;
+  clientStreaming: boolean;
+  serverStreaming: boolean;
+}
+/**
+ * Calling a gRPC service.
+ *
+ * `stream` hands back the whole sequence once it is complete rather than a live
+ * stream, so a flow reads it as an ordinary list.
+ *
+ * Two implementations: `createRealClient` and `createFakeClient`.
+ */
+interface GrpcClient {
+  call(call: GrpcCall): Promise<unknown>;
+  stream(call: GrpcCall): Promise<readonly unknown[]>;
+  reflect(service: string): Promise<readonly GrpcMethodInfo[]>;
+}
+//#endregion
+//#region src/port/grpc-client.port.d.ts
+/**
+ * The port descriptor every `grpc` verb resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot open a channel refuses
+ * the binding at load time with a readable diagnostic.
+ */
+declare const GrpcClientPort: Port<GrpcClient>;
+//#endregion
+//#region src/clients/fake-client.d.ts
+/**
+ * The double: canned answers, and no channel.
+ *
+ * Anything not named falls back to an empty value (`{}` for a call, `[]` for a
+ * stream or a reflection), so a test only lists what it cares about.
+ *
+ * @param config.responses Unary results, keyed by `package.Service/Method`.
+ * @param config.streams Streamed results, keyed by the same.
+ * @param config.reflection Method metadata, keyed by service name.
+ */
+declare function createFakeClient(config?: {
+  responses?: Record<string, unknown>;
+  streams?: Record<string, readonly unknown[]>;
+  reflection?: Record<string, readonly GrpcMethodInfo[]>;
+}): GrpcClient;
+//#endregion
+//#region src/clients/real-client.d.ts
+/**
+ * The real gRPC client. Not implemented in this build: proto loading, channels
+ * and reflection are out of scope here.
+ *
+ * It exists so the port has its second implementation and the failure is a named
+ * Venn error rather than a missing method.
+ *
+ * @throws VN8090 from every method.
+ */
+declare function createRealClient(): GrpcClient;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `grpc` namespace: `call`, `stream`, `reflect` and the `grpc.MethodInfo`
+ * type.
+ *
+ * Requires the `net` capability, so a host without it refuses the plugin at load
+ * time rather than failing mid-flow. No matchers: there is no typed subject to
+ * write one against.
+ */
+declare const grpcPlugin: PluginDefinition;
+//#endregion
+export { type GrpcCall, type GrpcClient, GrpcClientPort, type GrpcMethodInfo, createFakeClient, createRealClient, grpcPlugin as default, grpcPlugin };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/port/grpc-client.types.ts","../src/port/grpc-client.port.ts","../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/plugin.ts"],"mappings":";;;;UACiB;EACf;EACA,UAAU;;;UAIK;EACf;EACA;EACA;EACA;EACA;;;;;;;;;;UAWe;EACf,KAAK,MAAM,WAAW;EACtB,OAAO,MAAM,WAAW;EACxB,QAAQ,kBAAkB,iBAAiB;;;;;;;;;;cCjBhC,gBAAgB,KAAK;;;;;;;;;;;;;iBCGlB,iBACd;EACE,YAAY;EACZ,UAAU;EACV,aAAa,wBAAwB;IAEtC;;;;;;;;;;;;iBCNa,oBAAoB;;;;;;;;;;;cCAvB,YAAY"}

package/dist/index.js

@@ -0,0 +1,155 @@
+import { VennError } from "@venn-lang/contracts";
+import { arg, defineAction, definePlugin, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+//#region src/clients/fake-client.ts
+/**
+* The double: canned answers, and no channel.
+*
+* Anything not named falls back to an empty value (`{}` for a call, `[]` for a
+* stream or a reflection), so a test only lists what it cares about.
+*
+* @param config.responses Unary results, keyed by `package.Service/Method`.
+* @param config.streams Streamed results, keyed by the same.
+* @param config.reflection Method metadata, keyed by service name.
+*/
+function createFakeClient(config = {}) {
+	const { responses = {}, streams = {}, reflection = {} } = config;
+	return {
+		call: async (call) => responses[call.method] ?? {},
+		stream: async (call) => streams[call.method] ?? [],
+		reflect: async (service) => reflection[service] ?? []
+	};
+}
+//#endregion
+//#region src/clients/real-client.ts
+/**
+* The real gRPC client. Not implemented in this build: proto loading, channels
+* and reflection are out of scope here.
+*
+* It exists so the port has its second implementation and the failure is a named
+* Venn error rather than a missing method.
+*
+* @throws VN8090 from every method.
+*/
+function createRealClient() {
+	return {
+		async call() {
+			return unimplemented();
+		},
+		async stream() {
+			return unimplemented();
+		},
+		async reflect() {
+			return unimplemented();
+		}
+	};
+}
+function unimplemented() {
+	throw new VennError({
+		code: "VN8090",
+		message: "gRPC real client not implemented in this build"
+	});
+}
+//#endregion
+//#region src/port/grpc-client.port.ts
+/**
+* The port descriptor every `grpc` verb resolves through `ctx.port(...)`.
+*
+* Declares the `net` capability, so a host that cannot open a channel refuses
+* the binding at load time with a readable diagnostic.
+*/
+const GrpcClientPort = {
+	id: "venn.port.grpc-client",
+	version: 1,
+	requires: ["net"],
+	methods: [
+		"call",
+		"stream",
+		"reflect"
+	]
+};
+//#endregion
+//#region src/actions/grpc-action.ts
+const requestParams = z.record(z.string(), z.unknown()).optional();
+/**
+* `grpc.call "pkg.Service/Method" { id: 42 }`: one unary call.
+*
+* The method is the only positional argument and the options map is the request
+* message. The result is dynamic because its shape lives in a `.proto` this
+* plugin never reads.
+*/
+const callAction = defineAction({
+	name: "call",
+	doc: "Unary gRPC call.",
+	params: requestParams,
+	args: [arg("method", t.string, "The full method: `package.Service/Method`.")],
+	result: t.dynamic,
+	run: (ctx, input) => ctx.port(GrpcClientPort).call(buildCall(input))
+});
+/**
+* `grpc.stream "pkg.Service/Method" { id: 42 }`: a server-streaming call.
+*
+* The messages come back as a list, collected once the stream ends. A flow reads
+* it like any other list; there is nothing live to subscribe to.
+*/
+const streamAction = defineAction({
+	name: "stream",
+	doc: "Server-streaming gRPC call.",
+	params: requestParams,
+	args: [arg("method", t.string, "The full method: `package.Service/Method`.")],
+	result: t.list(t.dynamic),
+	run: (ctx, input) => ctx.port(GrpcClientPort).stream(buildCall(input))
+});
+/**
+* `grpc.reflect "pkg.Service"`: ask the server what methods it has.
+*
+* The one verb here with a typed result, because `grpc.MethodInfo` is described
+* by the reflection protocol rather than by anyone's `.proto`.
+*/
+const reflectAction = defineAction({
+	name: "reflect",
+	doc: "Server reflection: list a service's methods.",
+	args: [arg("service", t.string, "The service to ask about.")],
+	result: t.list(t.ref("grpc.MethodInfo")),
+	run: (ctx, input) => ctx.port(GrpcClientPort).reflect(String(input.args[0] ?? ""))
+});
+function buildCall(input) {
+	return {
+		method: String(input.args[0] ?? ""),
+		request: input.params ?? void 0
+	};
+}
+//#endregion
+//#region src/plugin.ts
+/**
+* The `grpc` namespace: `call`, `stream`, `reflect` and the `grpc.MethodInfo`
+* type.
+*
+* Requires the `net` capability, so a host without it refuses the plugin at load
+* time rather than failing mid-flow. No matchers: there is no typed subject to
+* write one against.
+*/
+const grpcPlugin = definePlugin({
+	name: "venn/grpc",
+	version: "0.0.0",
+	namespace: "grpc",
+	requires: ["net"],
+	actions: [
+		callAction,
+		streamAction,
+		reflectAction
+	],
+	typeDefs: { 
+	/** One RPC method, as server reflection describes it. */
+MethodInfo: t.record({
+		name: t.string,
+		requestType: t.string,
+		responseType: t.string,
+		clientStreaming: t.bool,
+		serverStreaming: t.bool
+	}) }
+});
+//#endregion
+export { GrpcClientPort, createFakeClient, createRealClient, grpcPlugin as default, grpcPlugin };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/port/grpc-client.port.ts","../src/actions/grpc-action.ts","../src/actions/index.ts","../src/types.ts","../src/plugin.ts"],"sourcesContent":["import type { GrpcClient, GrpcMethodInfo } from \"../port/index.js\";\n\n/**\n * The double: canned answers, and no channel.\n *\n * Anything not named falls back to an empty value (`{}` for a call, `[]` for a\n * stream or a reflection), so a test only lists what it cares about.\n *\n * @param config.responses Unary results, keyed by `package.Service/Method`.\n * @param config.streams Streamed results, keyed by the same.\n * @param config.reflection Method metadata, keyed by service name.\n */\nexport function createFakeClient(\n  config: {\n    responses?: Record<string, unknown>;\n    streams?: Record<string, readonly unknown[]>;\n    reflection?: Record<string, readonly GrpcMethodInfo[]>;\n  } = {},\n): GrpcClient {\n  const { responses = {}, streams = {}, reflection = {} } = config;\n  return {\n    call: async (call) => responses[call.method] ?? {},\n    stream: async (call) => streams[call.method] ?? [],\n    reflect: async (service) => reflection[service] ?? [],\n  };\n}\n","import { VennError } from \"@venn-lang/contracts\";\nimport type { GrpcClient } from \"../port/index.js\";\n\n/**\n * The real gRPC client. Not implemented in this build: proto loading, channels\n * and reflection are out of scope here.\n *\n * It exists so the port has its second implementation and the failure is a named\n * Venn error rather than a missing method.\n *\n * @throws VN8090 from every method.\n */\nexport function createRealClient(): GrpcClient {\n  return {\n    async call() {\n      return unimplemented();\n    },\n    async stream() {\n      return unimplemented();\n    },\n    async reflect() {\n      return unimplemented();\n    },\n  };\n}\n\nfunction unimplemented(): never {\n  throw new VennError({\n    code: \"VN8090\",\n    message: \"gRPC real client not implemented in this build\",\n  });\n}\n","import type { Port } from \"@venn-lang/contracts\";\nimport type { GrpcClient } from \"./grpc-client.types.js\";\n\n/**\n * The port descriptor every `grpc` verb resolves through `ctx.port(...)`.\n *\n * Declares the `net` capability, so a host that cannot open a channel refuses\n * the binding at load time with a readable diagnostic.\n */\nexport const GrpcClientPort: Port<GrpcClient> = {\n  id: \"venn.port.grpc-client\",\n  version: 1,\n  requires: [\"net\"],\n  methods: [\"call\", \"stream\", \"reflect\"],\n};\n","import { type ActionDefinition, type ActionInput, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { type GrpcCall, GrpcClientPort } from \"../port/index.js\";\n\nconst requestParams = z.record(z.string(), z.unknown()).optional();\n\n/**\n * `grpc.call \"pkg.Service/Method\" { id: 42 }`: one unary call.\n *\n * The method is the only positional argument and the options map is the request\n * message. The result is dynamic because its shape lives in a `.proto` this\n * plugin never reads.\n */\nexport const callAction: ActionDefinition = defineAction({\n  name: \"call\",\n  doc: \"Unary gRPC call.\",\n  params: requestParams,\n  args: [arg(\"method\", t.string, \"The full method: `package.Service/Method`.\")],\n  result: t.dynamic,\n  run: (ctx, input) => ctx.port(GrpcClientPort).call(buildCall(input)),\n});\n\n/**\n * `grpc.stream \"pkg.Service/Method\" { id: 42 }`: a server-streaming call.\n *\n * The messages come back as a list, collected once the stream ends. A flow reads\n * it like any other list; there is nothing live to subscribe to.\n */\nexport const streamAction: ActionDefinition = defineAction({\n  name: \"stream\",\n  doc: \"Server-streaming gRPC call.\",\n  params: requestParams,\n  args: [arg(\"method\", t.string, \"The full method: `package.Service/Method`.\")],\n  result: t.list(t.dynamic),\n  run: (ctx, input) => ctx.port(GrpcClientPort).stream(buildCall(input)),\n});\n\n/**\n * `grpc.reflect \"pkg.Service\"`: ask the server what methods it has.\n *\n * The one verb here with a typed result, because `grpc.MethodInfo` is described\n * by the reflection protocol rather than by anyone's `.proto`.\n */\nexport const reflectAction: ActionDefinition = defineAction({\n  name: \"reflect\",\n  doc: \"Server reflection: list a service's methods.\",\n  args: [arg(\"service\", t.string, \"The service to ask about.\")],\n  result: t.list(t.ref(\"grpc.MethodInfo\")),\n  run: (ctx, input) => ctx.port(GrpcClientPort).reflect(String(input.args[0] ?? \"\")),\n});\n\nfunction buildCall(input: ActionInput<unknown>): GrpcCall {\n  return {\n    method: String(input.args[0] ?? \"\"),\n    request: (input.params ?? undefined) as Record<string, unknown> | undefined,\n  };\n}\n","import type { ActionDefinition } from \"@venn-lang/sdk\";\nimport { callAction, reflectAction, streamAction } from \"./grpc-action.js\";\n\n/** The grpc namespace's verbs. */\nexport const grpcActions: ActionDefinition[] = [callAction, streamAction, reflectAction];\n","import { type TypeSpec, t } from \"@venn-lang/types\";\n\n/**\n * The types the plugin publishes to flows, as `grpc.MethodInfo`.\n *\n * Mirrors `GrpcMethodInfo` in `port/grpc-client.types.ts` by hand. Reflection is\n * the only thing this plugin can describe: a call's request and response come\n * from a `.proto` nobody here has read, so they stay dynamic.\n */\nexport const grpcTypeDefs: Readonly<Record<string, TypeSpec>> = {\n  /** One RPC method, as server reflection describes it. */\n  MethodInfo: t.record({\n    name: t.string,\n    requestType: t.string,\n    responseType: t.string,\n    clientStreaming: t.bool,\n    serverStreaming: t.bool,\n  }),\n};\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { grpcActions } from \"./actions/index.js\";\nimport { grpcTypeDefs } from \"./types.js\";\n\n/**\n * The `grpc` namespace: `call`, `stream`, `reflect` and the `grpc.MethodInfo`\n * type.\n *\n * Requires the `net` capability, so a host without it refuses the plugin at load\n * time rather than failing mid-flow. No matchers: there is no typed subject to\n * write one against.\n */\nexport const grpcPlugin: PluginDefinition = definePlugin({\n  name: \"venn/grpc\",\n  version: \"0.0.0\",\n  namespace: \"grpc\",\n  requires: [\"net\"],\n  actions: grpcActions,\n  typeDefs: grpcTypeDefs,\n});\n"],"mappings":";;;;;;;;;;;;;;AAYA,SAAgB,iBACd,SAII,CAAC,GACO;CACZ,MAAM,EAAE,YAAY,CAAC,GAAG,UAAU,CAAC,GAAG,aAAa,CAAC,MAAM;CAC1D,OAAO;EACL,MAAM,OAAO,SAAS,UAAU,KAAK,WAAW,CAAC;EACjD,QAAQ,OAAO,SAAS,QAAQ,KAAK,WAAW,CAAC;EACjD,SAAS,OAAO,YAAY,WAAW,YAAY,CAAC;CACtD;AACF;;;;;;;;;;;;ACbA,SAAgB,mBAA+B;CAC7C,OAAO;EACL,MAAM,OAAO;GACX,OAAO,cAAc;EACvB;EACA,MAAM,SAAS;GACb,OAAO,cAAc;EACvB;EACA,MAAM,UAAU;GACd,OAAO,cAAc;EACvB;CACF;AACF;AAEA,SAAS,gBAAuB;CAC9B,MAAM,IAAI,UAAU;EAClB,MAAM;EACN,SAAS;CACX,CAAC;AACH;;;;;;;;;ACtBA,MAAa,iBAAmC;CAC9C,IAAI;CACJ,SAAS;CACT,UAAU,CAAC,KAAK;CAChB,SAAS;EAAC;EAAQ;EAAU;CAAS;AACvC;;;ACVA,MAAM,gBAAgB,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS;;;;;;;;AASjE,MAAa,aAA+B,aAAa;CACvD,MAAM;CACN,KAAK;CACL,QAAQ;CACR,MAAM,CAAC,IAAI,UAAU,EAAE,QAAQ,4CAA4C,CAAC;CAC5E,QAAQ,EAAE;CACV,MAAM,KAAK,UAAU,IAAI,KAAK,cAAc,CAAC,CAAC,KAAK,UAAU,KAAK,CAAC;AACrE,CAAC;;;;;;;AAQD,MAAa,eAAiC,aAAa;CACzD,MAAM;CACN,KAAK;CACL,QAAQ;CACR,MAAM,CAAC,IAAI,UAAU,EAAE,QAAQ,4CAA4C,CAAC;CAC5E,QAAQ,EAAE,KAAK,EAAE,OAAO;CACxB,MAAM,KAAK,UAAU,IAAI,KAAK,cAAc,CAAC,CAAC,OAAO,UAAU,KAAK,CAAC;AACvE,CAAC;;;;;;;AAQD,MAAa,gBAAkC,aAAa;CAC1D,MAAM;CACN,KAAK;CACL,MAAM,CAAC,IAAI,WAAW,EAAE,QAAQ,2BAA2B,CAAC;CAC5D,QAAQ,EAAE,KAAK,EAAE,IAAI,iBAAiB,CAAC;CACvC,MAAM,KAAK,UAAU,IAAI,KAAK,cAAc,CAAC,CAAC,QAAQ,OAAO,MAAM,KAAK,MAAM,EAAE,CAAC;AACnF,CAAC;AAED,SAAS,UAAU,OAAuC;CACxD,OAAO;EACL,QAAQ,OAAO,MAAM,KAAK,MAAM,EAAE;EAClC,SAAU,MAAM,UAAU,KAAA;CAC5B;AACF;;;;;;;;;;;AG5CA,MAAa,aAA+B,aAAa;CACvD,MAAM;CACN,SAAS;CACT,WAAW;CACX,UAAU,CAAC,KAAK;CAChB,SAAS;EFbqC;EAAY;EAAc;CEa/D;CACT,UAAU;;ADPV,YAAY,EAAE,OAAO;EACnB,MAAM,EAAE;EACR,aAAa,EAAE;EACf,cAAc,EAAE;EAChB,iBAAiB,EAAE;EACnB,iBAAiB,EAAE;CACrB,CAAC,ECCS;AACZ,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@venn-lang/grpc",
+  "version": "0.1.0",
+  "description": "The grpc namespace: unary calls, server streams and server reflection as Venn verbs.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "grpc"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-grpc#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-grpc"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/contracts": "0.1.0",
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/grpc-action.ts

@@ -0,0 +1,57 @@
+import { type ActionDefinition, type ActionInput, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { type GrpcCall, GrpcClientPort } from "../port/index.js";
+
+const requestParams = z.record(z.string(), z.unknown()).optional();
+
+/**
+ * `grpc.call "pkg.Service/Method" { id: 42 }`: one unary call.
+ *
+ * The method is the only positional argument and the options map is the request
+ * message. The result is dynamic because its shape lives in a `.proto` this
+ * plugin never reads.
+ */
+export const callAction: ActionDefinition = defineAction({
+  name: "call",
+  doc: "Unary gRPC call.",
+  params: requestParams,
+  args: [arg("method", t.string, "The full method: `package.Service/Method`.")],
+  result: t.dynamic,
+  run: (ctx, input) => ctx.port(GrpcClientPort).call(buildCall(input)),
+});
+
+/**
+ * `grpc.stream "pkg.Service/Method" { id: 42 }`: a server-streaming call.
+ *
+ * The messages come back as a list, collected once the stream ends. A flow reads
+ * it like any other list; there is nothing live to subscribe to.
+ */
+export const streamAction: ActionDefinition = defineAction({
+  name: "stream",
+  doc: "Server-streaming gRPC call.",
+  params: requestParams,
+  args: [arg("method", t.string, "The full method: `package.Service/Method`.")],
+  result: t.list(t.dynamic),
+  run: (ctx, input) => ctx.port(GrpcClientPort).stream(buildCall(input)),
+});
+
+/**
+ * `grpc.reflect "pkg.Service"`: ask the server what methods it has.
+ *
+ * The one verb here with a typed result, because `grpc.MethodInfo` is described
+ * by the reflection protocol rather than by anyone's `.proto`.
+ */
+export const reflectAction: ActionDefinition = defineAction({
+  name: "reflect",
+  doc: "Server reflection: list a service's methods.",
+  args: [arg("service", t.string, "The service to ask about.")],
+  result: t.list(t.ref("grpc.MethodInfo")),
+  run: (ctx, input) => ctx.port(GrpcClientPort).reflect(String(input.args[0] ?? "")),
+});
+
+function buildCall(input: ActionInput<unknown>): GrpcCall {
+  return {
+    method: String(input.args[0] ?? ""),
+    request: (input.params ?? undefined) as Record<string, unknown> | undefined,
+  };
+}

package/src/actions/index.ts

@@ -0,0 +1,5 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+import { callAction, reflectAction, streamAction } from "./grpc-action.js";
+
+/** The grpc namespace's verbs. */
+export const grpcActions: ActionDefinition[] = [callAction, streamAction, reflectAction];

package/src/clients/fake-client.ts

@@ -0,0 +1,26 @@
+import type { GrpcClient, GrpcMethodInfo } from "../port/index.js";
+
+/**
+ * The double: canned answers, and no channel.
+ *
+ * Anything not named falls back to an empty value (`{}` for a call, `[]` for a
+ * stream or a reflection), so a test only lists what it cares about.
+ *
+ * @param config.responses Unary results, keyed by `package.Service/Method`.
+ * @param config.streams Streamed results, keyed by the same.
+ * @param config.reflection Method metadata, keyed by service name.
+ */
+export function createFakeClient(
+  config: {
+    responses?: Record<string, unknown>;
+    streams?: Record<string, readonly unknown[]>;
+    reflection?: Record<string, readonly GrpcMethodInfo[]>;
+  } = {},
+): GrpcClient {
+  const { responses = {}, streams = {}, reflection = {} } = config;
+  return {
+    call: async (call) => responses[call.method] ?? {},
+    stream: async (call) => streams[call.method] ?? [],
+    reflect: async (service) => reflection[service] ?? [],
+  };
+}

package/src/clients/index.ts

@@ -0,0 +1,2 @@
+export { createFakeClient } from "./fake-client.js";
+export { createRealClient } from "./real-client.js";

package/src/clients/real-client.ts

@@ -0,0 +1,32 @@
+import { VennError } from "@venn-lang/contracts";
+import type { GrpcClient } from "../port/index.js";
+
+/**
+ * The real gRPC client. Not implemented in this build: proto loading, channels
+ * and reflection are out of scope here.
+ *
+ * It exists so the port has its second implementation and the failure is a named
+ * Venn error rather than a missing method.
+ *
+ * @throws VN8090 from every method.
+ */
+export function createRealClient(): GrpcClient {
+  return {
+    async call() {
+      return unimplemented();
+    },
+    async stream() {
+      return unimplemented();
+    },
+    async reflect() {
+      return unimplemented();
+    },
+  };
+}
+
+function unimplemented(): never {
+  throw new VennError({
+    code: "VN8090",
+    message: "gRPC real client not implemented in this build",
+  });
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * The `grpc` plugin: `call`, `stream` and `reflect`.
+ *
+ * Requests and responses stay dynamic because their shape lives in a `.proto`
+ * this package never reads. Reflection is the one thing it can type.
+ */
+
+export * from "./clients/index.js";
+export { grpcPlugin, grpcPlugin as default } from "./plugin.js";
+export * from "./port/index.js";

package/src/plugin.ts

@@ -0,0 +1,20 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { grpcActions } from "./actions/index.js";
+import { grpcTypeDefs } from "./types.js";
+
+/**
+ * The `grpc` namespace: `call`, `stream`, `reflect` and the `grpc.MethodInfo`
+ * type.
+ *
+ * Requires the `net` capability, so a host without it refuses the plugin at load
+ * time rather than failing mid-flow. No matchers: there is no typed subject to
+ * write one against.
+ */
+export const grpcPlugin: PluginDefinition = definePlugin({
+  name: "venn/grpc",
+  version: "0.0.0",
+  namespace: "grpc",
+  requires: ["net"],
+  actions: grpcActions,
+  typeDefs: grpcTypeDefs,
+});

package/src/port/grpc-client.port.ts

@@ -0,0 +1,15 @@
+import type { Port } from "@venn-lang/contracts";
+import type { GrpcClient } from "./grpc-client.types.js";
+
+/**
+ * The port descriptor every `grpc` verb resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot open a channel refuses
+ * the binding at load time with a readable diagnostic.
+ */
+export const GrpcClientPort: Port<GrpcClient> = {
+  id: "venn.port.grpc-client",
+  version: 1,
+  requires: ["net"],
+  methods: ["call", "stream", "reflect"],
+};

package/src/port/grpc-client.types.ts

@@ -0,0 +1,28 @@
+/** One invocation: the full `package.Service/Method`, plus the request message. */
+export interface GrpcCall {
+  method: string;
+  request?: Record<string, unknown>;
+}
+
+/** Metadata for one RPC method, as returned by server reflection. */
+export interface GrpcMethodInfo {
+  name: string;
+  requestType: string;
+  responseType: string;
+  clientStreaming: boolean;
+  serverStreaming: boolean;
+}
+
+/**
+ * Calling a gRPC service.
+ *
+ * `stream` hands back the whole sequence once it is complete rather than a live
+ * stream, so a flow reads it as an ordinary list.
+ *
+ * Two implementations: `createRealClient` and `createFakeClient`.
+ */
+export interface GrpcClient {
+  call(call: GrpcCall): Promise<unknown>;
+  stream(call: GrpcCall): Promise<readonly unknown[]>;
+  reflect(service: string): Promise<readonly GrpcMethodInfo[]>;
+}

package/src/port/index.ts

@@ -0,0 +1,2 @@
+export { GrpcClientPort } from "./grpc-client.port.js";
+export type { GrpcCall, GrpcClient, GrpcMethodInfo } from "./grpc-client.types.js";

package/src/types.ts

@@ -0,0 +1,19 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The types the plugin publishes to flows, as `grpc.MethodInfo`.
+ *
+ * Mirrors `GrpcMethodInfo` in `port/grpc-client.types.ts` by hand. Reflection is
+ * the only thing this plugin can describe: a call's request and response come
+ * from a `.proto` nobody here has read, so they stay dynamic.
+ */
+export const grpcTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /** One RPC method, as server reflection describes it. */
+  MethodInfo: t.record({
+    name: t.string,
+    requestType: t.string,
+    responseType: t.string,
+    clientStreaming: t.bool,
+    serverStreaming: t.bool,
+  }),
+};