feat: Add rpc-methods package

- Add rpc-methods package for internal RPC calls
- Consolidate PromiseCallbacks type into utils package

Author: rekmarks

packages/extension/src/kernel-integration/VatWorkerClient.ts

@@ -1,5 +1,4 @@
 import { makePromiseKit } from '@endo/promise-kit';
-import type { PromiseKit } from '@endo/promise-kit';
 import { isObject } from '@metamask/utils';
 import {
   isVatCommandReply,
@@ -24,15 +23,13 @@ import type {
   PostMessageEnvelope,
   PostMessageTarget,
 } from '@ocap/streams/browser';
-import type { Logger } from '@ocap/utils';
+import type { Logger, PromiseCallbacks } from '@ocap/utils';
 import { makeCounter, makeLogger } from '@ocap/utils';
 
 // Appears in the docs.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type { ExtensionVatWorkerServer } from './VatWorkerServer.ts';
 
-type PromiseCallbacks<Resolve = unknown> = Omit<PromiseKit<Resolve>, 'promise'>;
-
 export type VatWorkerClientStream = PostMessageDuplexStream<
   MessageEvent<VatWorkerServiceReply>,
   PostMessageEnvelope<VatWorkerServiceCommand>

packages/kernel/src/VatHandle.ts

@@ -8,7 +8,7 @@ import { makePromiseKit } from '@endo/promise-kit';
 import { VatDeletedError, StreamReadError } from '@ocap/errors';
 import type { VatStore } from '@ocap/store';
 import type { DuplexStream } from '@ocap/streams';
-import type { Logger } from '@ocap/utils';
+import type { Logger, PromiseCallbacks } from '@ocap/utils';
 import { makeLogger, makeCounter } from '@ocap/utils';
 
 import type { Kernel } from './Kernel.ts';
@@ -22,7 +22,6 @@ import { kser } from './services/kernel-marshal.ts';
 import type { KernelStore } from './store/index.ts';
 import { parseRef } from './store/utils/parse-ref.ts';
 import type {
-  PromiseCallbacks,
   VatId,
   VatConfig,
   VRef,

packages/kernel/src/messages/message-resolver.ts

@@ -1,7 +1,6 @@
 import { makePromiseKit } from '@endo/promise-kit';
 import { makeCounter } from '@ocap/utils';
-
-import type { PromiseCallbacks } from '../types.ts';
+import type { PromiseCallbacks } from '@ocap/utils';
 
 export class MessageResolver {
   readonly #prefix: string;

packages/kernel/src/types.ts

@@ -1,6 +1,5 @@
 import type { Message } from '@agoric/swingset-liveslots';
 import type { CapData } from '@endo/marshal';
-import type { PromiseKit } from '@endo/promise-kit';
 import {
   define,
   is,
@@ -200,11 +199,6 @@ export const VatMessageIdStruct = define<VatMessageId>(
   isVatMessageId,
 );
 
-export type PromiseCallbacks<Resolve = unknown> = Omit<
-  PromiseKit<Resolve>,
-  'promise'
->;
-
 export type VatWorkerService = {
   /**
    * Launch a new worker with a specific vat id.

packages/rpc-methods/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+[Unreleased]: https://github.com/MetaMask/ocap-kernel/

packages/rpc-methods/README.md

@@ -0,0 +1,15 @@
+# `@ocap/rpc-methods`
+
+Utilities for implementing JSON-RPC methods
+
+## Installation
+
+`yarn add @ocap/rpc-methods`
+
+or
+
+`npm install @ocap/rpc-methods`
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/ocap-kernel#readme).

packages/rpc-methods/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@ocap/rpc-methods",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Utilities for implementing JSON-RPC methods",
+  "homepage": "https://github.com/MetaMask/ocap-kernel/tree/main/packages/rpc-methods#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/ocap-kernel/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/ocap-kernel.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "ts-bridge --project tsconfig.build.json --clean",
+    "build:docs": "typedoc",
+    "changelog:validate": "../../scripts/validate-changelog.sh @ocap/rpc-methods",
+    "clean": "rimraf --glob './*.tsbuildinfo' ./.eslintcache ./coverage ./dist",
+    "lint": "yarn lint:eslint && yarn lint:misc --check && yarn constraints && yarn lint:dependencies",
+    "lint:dependencies": "depcheck",
+    "lint:eslint": "eslint . --cache",
+    "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write && yarn constraints --fix && yarn lint:dependencies",
+    "lint:misc": "prettier --no-error-on-unmatched-pattern '**/*.json' '**/*.md' '**/*.html' '!**/CHANGELOG.old.md' '**/*.yml' '!.yarnrc.yml' '!merged-packages/**' --ignore-path ../../.gitignore",
+    "publish:preview": "yarn npm publish --tag preview",
+    "test": "vitest run --config vitest.config.ts",
+    "test:clean": "yarn test --no-cache --coverage.clean",
+    "test:dev": "yarn test --mode development",
+    "test:verbose": "yarn test --reporter verbose",
+    "test:watch": "vitest --config vitest.config.ts"
+  },
+  "dependencies": {
+    "@endo/promise-kit": "^1.1.6",
+    "@metamask/superstruct": "^3.2.0",
+    "@metamask/utils": "^11.3.0",
+    "@ocap/utils": "workspace:^"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.17.3",
+    "@metamask/auto-changelog": "^4.0.0",
+    "@metamask/eslint-config": "^14.0.0",
+    "@metamask/eslint-config-nodejs": "^14.0.0",
+    "@metamask/eslint-config-typescript": "^14.0.0",
+    "@ocap/test-utils": "workspace:^",
+    "@ts-bridge/cli": "^0.6.2",
+    "@ts-bridge/shims": "^0.1.1",
+    "@typescript-eslint/eslint-plugin": "^8.26.1",
+    "@typescript-eslint/parser": "^8.26.1",
+    "@typescript-eslint/utils": "^8.26.1",
+    "@vitest/eslint-plugin": "^1.1.25",
+    "depcheck": "^1.4.7",
+    "eslint": "^9.12.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-import-resolver-typescript": "^3.8.4",
+    "eslint-plugin-import-x": "^4.3.1",
+    "eslint-plugin-jsdoc": "^50.3.1",
+    "eslint-plugin-n": "^17.11.1",
+    "eslint-plugin-prettier": "^5.2.1",
+    "eslint-plugin-promise": "^7.1.0",
+    "prettier": "^3.3.3",
+    "rimraf": "^6.0.1",
+    "typedoc": "^0.27.9",
+    "typescript": "~5.8.2",
+    "typescript-eslint": "^8.26.1",
+    "vite": "^6.0.11",
+    "vitest": "^3.0.5"
+  },
+  "engines": {
+    "node": "^20 || >=22"
+  }
+}

packages/rpc-methods/src/RpcClient.test.ts

@@ -0,0 +1,93 @@
+import { string } from '@metamask/superstruct';
+import { jsonrpc2 } from '@metamask/utils';
+import { describe, it, vi, expect } from 'vitest';
+
+import { RpcClient } from './RpcClient.ts';
+
+const getMethods = () =>
+  ({
+    method1: {
+      method: 'method1',
+      result: string(),
+    },
+  }) as const;
+
+describe('RpcClient', () => {
+  describe('constructor', () => {
+    it('should create a new RpcClient', () => {
+      const client = new RpcClient(getMethods(), vi.fn(), 'test');
+      expect(client).toBeInstanceOf(RpcClient);
+    });
+  });
+
+  describe('call', () => {
+    it('should call a method', async () => {
+      const client = new RpcClient(getMethods(), vi.fn(), 'test');
+      const resultP = client.call('method1', 'test');
+      client.handleResponse('test:1', {
+        jsonrpc: jsonrpc2,
+        id: 'test:1',
+        result: 'test',
+      });
+
+      expect(await resultP).toBe('test');
+    });
+
+    it('should throw an error for error responses', async () => {
+      const client = new RpcClient(getMethods(), vi.fn(), 'test');
+      const resultP = client.call('method1', 'test');
+      client.handleResponse('test:1', {
+        jsonrpc: jsonrpc2,
+        id: 'test:1',
+        error: {
+          code: -32000,
+          message: 'test error',
+        },
+      });
+
+      await expect(resultP).rejects.toThrow('test error');
+    });
+
+    it('should throw an error for invalid results', async () => {
+      const client = new RpcClient(getMethods(), vi.fn(), 'test');
+      const resultP = client.call('method1', 'test');
+      client.handleResponse('test:1', {
+        jsonrpc: jsonrpc2,
+        id: 'test:1',
+        result: 42,
+      });
+      await expect(resultP).rejects.toThrow(
+        'Invalid result: Expected a string, but received: 42',
+      );
+    });
+
+    it('should throw an error for invalid responses', async () => {
+      const client = new RpcClient(getMethods(), vi.fn(), 'test');
+      const resultP = client.call('method1', 'test');
+      client.handleResponse('test:1', 'invalid');
+      await expect(resultP).rejects.toThrow('Invalid JSON-RPC response:');
+    });
+  });
+
+  describe('handleResponse', () => {
+    it('should log an error if the message id is not found', () => {
+      const client = new RpcClient(getMethods(), vi.fn(), 'test');
+      const logError = vi.spyOn(console, 'error');
+      client.handleResponse('test:1', 'test');
+      expect(logError).toHaveBeenCalledWith(
+        'No unresolved message with id "test:1".',
+      );
+    });
+  });
+
+  describe('rejectAll', () => {
+    it('should reject all unresolved messages', async () => {
+      const client = new RpcClient(getMethods(), vi.fn(), 'test');
+      const p1 = client.call('method1', 'test');
+      const p2 = client.call('method1', 'test');
+      client.rejectAll(new Error('test error'));
+      await expect(p1).rejects.toThrow('test error');
+      await expect(p2).rejects.toThrow('test error');
+    });
+  });
+});