@metamask-previews/json-rpc-engine 7.2.0-preview.80566a6

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# 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]
+
+## [7.2.0]
+### Added
+- Applied eslint rules from core monorepo ([#172](https://github.com/MetaMask/json-rpc-engine/pull/172))
+
+## [7.1.1]
+### Changed
+- Bumped `@metamask/utils` from `^5.0.2` to `^8.1.0` [#158](https://github.com/MetaMask/json-rpc-engine/pull/158) ([#162](https://github.com/MetaMask/json-rpc-engine/pull/162))
+- Bumped `@metamask/rpc-errors` from `^5.0.0` to `^6.0.0` ([#162](https://github.com/MetaMask/json-rpc-engine/pull/162))
+
+## [7.1.0]
+### Changed
+- Bumped `@metamask/safe-event-emitter` from `^2.0.0` to `^3.0.0` ([#148](https://github.com/MetaMask/json-rpc-engine/pull/148))
+- Bumped `@metamask/utils` from `^5.0.1` to `^5.0.2` ([#151](https://github.com/MetaMask/json-rpc-engine/pull/151))
+
+### Fixed
+- Fixed handling of empty batch array in requests ([#153](https://github.com/MetaMask/json-rpc-engine/pull/153))
+
+## [7.0.0]
+### Added
+- Added JSON-RPC notification handling ([#104](https://github.com/MetaMask/json-rpc-engine/pull/104))
+- Added `destroy` method ([#106](https://github.com/MetaMask/json-rpc-engine/pull/106))
+
+### Changed
+- **BREAKING:** Require a minimum Node version of 16 ([#139](https://github.com/MetaMask/json-rpc-engine/pull/139))
+- **BREAKING:** Use `@metamask/utils` types ([#105](https://github.com/MetaMask/json-rpc-engine/pull/105))
+  - The JSON-RPC engine and all middleware now use `@metamask/utils` JSON-RPC types
+- **(BREAKING)** Return a `null` instead of `undefined` response `id` for malformed request objects ([#91](https://github.com/MetaMask/json-rpc-engine/pull/91))
+  - This is very unlikely to be breaking in practice, but the behavior could have been relied on.
+- Change package name to `@metamask/json-rpc-engine` ([#139](https://github.com/MetaMask/json-rpc-engine/pull/139))
+- Use `@metamask/rpc-errors` ([#138](https://github.com/MetaMask/json-rpc-engine/pull/138))
+
+## [6.1.0] - 2020-11-20
+### Added
+- Add `PendingJsonRpcResponse` interface for use in middleware ([#75](https://github.com/MetaMask/json-rpc-engine/pull/75))
+
+### Changed
+- Use `async`/`await` and `try`/`catch` instead of Promise methods everywhere ([#74](https://github.com/MetaMask/json-rpc-engine/pull/74))
+  - Consumers may notice improved stack traces on certain platforms.
+
+## [6.0.0] - 2020-11-19
+### Added
+- Add docstrings for public `JsonRpcEngine` methods ([#70](https://github.com/MetaMask/json-rpc-engine/pull/70))
+
+### Changed
+- **(BREAKING)** Refactor exports ([#69](https://github.com/MetaMask/json-rpc-engine/pull/69))
+  - All exports are now named, and available via the package entry point.
+  - All default exports have been removed.
+- **(BREAKING)** Convert `asMiddleware` to instance method ([#69](https://github.com/MetaMask/json-rpc-engine/pull/69))
+  - The `asMiddleware` export has been removed.
+- **(BREAKING)** Add runtime typechecks to `JsonRpcEngine.handle()`, and error responses if they fail ([#70](https://github.com/MetaMask/json-rpc-engine/pull/70))
+  - Requests will now error if:
+    - The request is not a plain object, or if the `method` property is not a `string`. Empty strings are allowed.
+    - A `next` middleware callback is called with a truthy, non-function parameter.
+- Migrate to TypeScript ([#69](https://github.com/MetaMask/json-rpc-engine/pull/69))
+- Hopefully improve stack traces by removing uses of `Promise.then` and `.catch` internally ([#70](https://github.com/MetaMask/json-rpc-engine/pull/70))
+- Make some internal `JsonRpcEngine` methods `static` ([#71](https://github.com/MetaMask/json-rpc-engine/pull/71))
+
+## [5.4.0] - 2020-11-07
+### Changed
+- Make the TypeScript types not terrible ([#66](https://github.com/MetaMask/json-rpc-engine/pull/66), [#67](https://github.com/MetaMask/json-rpc-engine/pull/67))
+
+## [5.3.0] - 2020-07-30
+### Changed
+- Response object errors no longer include a `stack` property
+
+## [5.2.0] - 2020-07-24
+### Added
+- Promise signatures for `engine.handle` ([#55](https://github.com/MetaMask/json-rpc-engine/pull/55))
+  - So, in addition to `engine.handle(request, callback)`, you can do e.g. `await engine.handle(request)`.
+
+### Changed
+- Remove `async` and `promise-to-callback` dependencies
+  - These dependencies were used internally for middleware flow control.
+    They have been replaced with Promises and native `async`/`await`, which means that some operations are _no longer_ eagerly executed.
+    This change may affect consumers that depend on the eager execution of middleware _during_ request processing, _outside of_ middleware functions and request handlers.
+    - In general, it is a bad practice to work with state that depends on middleware execution, while the middleware are executing.
+
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/json-rpc-engine@7.2.0...HEAD
+[7.2.0]: https://github.com/MetaMask/core/compare/@metamask/json-rpc-engine@7.1.1...@metamask/json-rpc-engine@7.2.0
+[7.1.1]: https://github.com/MetaMask/core/compare/@metamask/json-rpc-engine@7.1.0...@metamask/json-rpc-engine@7.1.1
+[7.1.0]: https://github.com/MetaMask/core/compare/@metamask/json-rpc-engine@7.0.0...@metamask/json-rpc-engine@7.1.0
+[7.0.0]: https://github.com/MetaMask/core/compare/json-rpc-engine@6.1.0...@metamask/json-rpc-engine@7.0.0
+[6.1.0]: https://github.com/MetaMask/core/compare/json-rpc-engine@6.0.0...json-rpc-engine@6.1.0
+[6.0.0]: https://github.com/MetaMask/core/compare/json-rpc-engine@5.4.0...json-rpc-engine@6.0.0
+[5.4.0]: https://github.com/MetaMask/core/compare/json-rpc-engine@5.3.0...json-rpc-engine@5.4.0
+[5.3.0]: https://github.com/MetaMask/core/compare/json-rpc-engine@5.2.0...json-rpc-engine@5.3.0
+[5.2.0]: https://github.com/MetaMask/core/releases/tag/json-rpc-engine@5.2.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2022 MetaMask
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# `@metamask/json-rpc-engine`
+
+A tool for processing JSON-RPC requests and responses.
+
+## Usage
+
+```js
+const { JsonRpcEngine } = require('@metamask/json-rpc-engine');
+
+const engine = new JsonRpcEngine();
+```
+
+Build a stack of JSON-RPC processors by pushing middleware to the engine.
+
+```js
+engine.push(function (req, res, next, end) {
+  res.result = 42;
+  end();
+});
+```
+
+Requests are handled asynchronously, stepping down the stack until complete.
+
+```js
+const request = { id: 1, jsonrpc: '2.0', method: 'hello' };
+
+engine.handle(request, function (err, response) {
+  // Do something with response.result, or handle response.error
+});
+
+// There is also a Promise signature
+const response = await engine.handle(request);
+```
+
+Middleware have direct access to the request and response objects.
+They can let processing continue down the stack with `next()`, or complete the request with `end()`.
+
+```js
+engine.push(function (req, res, next, end) {
+  if (req.skipCache) return next();
+  res.result = getResultFromCache(req);
+  end();
+});
+```
+
+By passing a _return handler_ to the `next` function, you can get a peek at the result before it returns.
+
+```js
+engine.push(function (req, res, next, end) {
+  next(function (cb) {
+    insertIntoCache(res, cb);
+  });
+});
+```
+
+If you specify a `notificationHandler` when constructing the engine, JSON-RPC notifications passed to `handle()` will be handed off directly to this function without touching the middleware stack:
+
+```js
+const engine = new JsonRpcEngine({ notificationHandler });
+
+// A notification is defined as a JSON-RPC request without an `id` property.
+const notification = { jsonrpc: '2.0', method: 'hello' };
+
+const response = await engine.handle(notification);
+console.log(typeof response); // 'undefined'
+```
+
+Engines can be nested by converting them to middleware using `JsonRpcEngine.asMiddleware()`:
+
+```js
+const engine = new JsonRpcEngine();
+const subengine = new JsonRpcEngine();
+engine.push(subengine.asMiddleware());
+```
+
+### `async` Middleware
+
+If you require your middleware function to be `async`, use `createAsyncMiddleware`:
+
+```js
+const { createAsyncMiddleware } = require('@metamask/json-rpc-engine');
+
+let engine = new RpcEngine();
+engine.push(
+  createAsyncMiddleware(async (req, res, next) => {
+    res.result = 42;
+    next();
+  }),
+);
+```
+
+`async` middleware do not take an `end` callback.
+Instead, the request ends if the middleware returns without calling `next()`:
+
+```js
+engine.push(
+  createAsyncMiddleware(async (req, res, next) => {
+    res.result = 42;
+    /* The request will end when this returns */
+  }),
+);
+```
+
+The `next` callback of `async` middleware also don't take return handlers.
+Instead, you can `await next()`.
+When the execution of the middleware resumes, you can work with the response again.
+
+```js
+engine.push(
+  createAsyncMiddleware(async (req, res, next) => {
+    res.result = 42;
+    await next();
+    /* Your return handler logic goes here */
+    addToMetrics(res);
+  }),
+);
+```
+
+You can freely mix callback-based and `async` middleware:
+
+```js
+engine.push(function (req, res, next, end) {
+  if (!isCached(req)) {
+    return next((cb) => {
+      insertIntoCache(res, cb);
+    });
+  }
+  res.result = getResultFromCache(req);
+  end();
+});
+
+engine.push(
+  createAsyncMiddleware(async (req, res, next) => {
+    res.result = 42;
+    await next();
+    addToMetrics(res);
+  }),
+);
+```
+
+### Teardown
+
+If your middleware has teardown to perform, you can assign a method `destroy()` to your middleware function(s),
+and calling `JsonRpcEngine.destroy()` will call this method on each middleware that has it.
+A destroyed engine can no longer be used.
+
+```js
+const middleware = (req, res, next, end) => {
+  /* do something */
+};
+middleware.destroy = () => {
+  /* perform teardown */
+};
+
+const engine = new JsonRpcEngine();
+engine.push(middleware);
+
+/* perform work */
+
+// This will call middleware.destroy() and destroy the engine itself.
+engine.destroy();
+
+// Calling any public method on the middleware other than `destroy()` itself
+// will throw an error.
+engine.handle(req);
+```
+
+### Gotchas
+
+Handle errors via `end(err)`, _NOT_ `next(err)`.
+
+```js
+/* INCORRECT */
+engine.push(function (req, res, next, end) {
+  next(new Error());
+});
+
+/* CORRECT */
+engine.push(function (req, res, next, end) {
+  end(new Error());
+});
+```
+
+However, `next()` will detect errors on the response object, and cause
+`end(res.error)` to be called.
+
+```js
+engine.push(function (req, res, next, end) {
+  res.error = new Error();
+  next(); /* This will cause end(res.error) to be called. */
+});
+```
+
+## Running tests
+
+Build the project if not already built:
+
+```bash
+yarn build
+```
+
+```bash
+yarn test
+```

package/dist/JsonRpcEngine.d.ts

@@ -0,0 +1,114 @@
+import SafeEventEmitter from '@metamask/safe-event-emitter';
+import type { JsonRpcError as SerializedJsonRpcError, JsonRpcRequest, JsonRpcResponse, JsonRpcNotification, Json, JsonRpcParams, PendingJsonRpcResponse } from '@metamask/utils';
+export declare type JsonRpcEngineCallbackError = Error | SerializedJsonRpcError | null;
+export declare type JsonRpcEngineReturnHandler = (done: (error?: JsonRpcEngineCallbackError) => void) => void;
+export declare type JsonRpcEngineNextCallback = (returnHandlerCallback?: JsonRpcEngineReturnHandler) => void;
+export declare type JsonRpcEngineEndCallback = (error?: JsonRpcEngineCallbackError) => void;
+export declare type JsonRpcMiddleware<Params extends JsonRpcParams, Result extends Json> = {
+    (req: JsonRpcRequest<Params>, res: PendingJsonRpcResponse<Result>, next: JsonRpcEngineNextCallback, end: JsonRpcEngineEndCallback): void;
+    destroy?: () => void | Promise<void>;
+};
+export declare type JsonRpcNotificationHandler<Params extends JsonRpcParams> = (notification: JsonRpcNotification<Params>) => void | Promise<void>;
+declare type JsonRpcEngineArgs = {
+    /**
+     * A function for handling JSON-RPC notifications. A JSON-RPC notification is
+     * defined as a JSON-RPC request without an `id` property. If this option is
+     * _not_ provided, notifications will be treated the same as requests. If this
+     * option _is_ provided, notifications will be passed to the handler
+     * function without touching the engine's middleware stack.
+     *
+     * This function should not throw or reject.
+     */
+    notificationHandler?: JsonRpcNotificationHandler<JsonRpcParams>;
+};
+/**
+ * A JSON-RPC request and response processor.
+ * Give it a stack of middleware, pass it requests, and get back responses.
+ */
+export declare class JsonRpcEngine extends SafeEventEmitter {
+    #private;
+    /**
+     * Constructs a {@link JsonRpcEngine} instance.
+     *
+     * @param options - Options bag.
+     * @param options.notificationHandler - A function for handling JSON-RPC
+     * notifications. A JSON-RPC notification is defined as a JSON-RPC request
+     * without an `id` property. If this option is _not_ provided, notifications
+     * will be treated the same as requests. If this option _is_ provided,
+     * notifications will be passed to the handler function without touching
+     * the engine's middleware stack. This function should not throw or reject.
+     */
+    constructor({ notificationHandler }?: JsonRpcEngineArgs);
+    /**
+     * Calls the `destroy()` function of any middleware with that property, clears
+     * the middleware array, and marks this engine as destroyed. A destroyed
+     * engine cannot be used.
+     */
+    destroy(): void;
+    /**
+     * Add a middleware function to the engine's middleware stack.
+     *
+     * @param middleware - The middleware function to add.
+     */
+    push<Params extends JsonRpcParams, Result extends Json>(middleware: JsonRpcMiddleware<Params, Result>): void;
+    /**
+     * Handle a JSON-RPC request, and return a response.
+     *
+     * @param request - The request to handle.
+     * @param callback - An error-first callback that will receive the response.
+     */
+    handle<Params extends JsonRpcParams, Result extends Json>(request: JsonRpcRequest<Params>, callback: (error: unknown, response: JsonRpcResponse<Result>) => void): void;
+    /**
+     * Handle a JSON-RPC notification.
+     *
+     * @param notification - The notification to handle.
+     * @param callback - An error-first callback that will receive a `void` response.
+     */
+    handle<Params extends JsonRpcParams>(notification: JsonRpcNotification<Params>, callback: (error: unknown, response: void) => void): void;
+    /**
+     * Handle an array of JSON-RPC requests and/or notifications, and return an
+     * array of responses to any included requests.
+     *
+     * @param request - The requests to handle.
+     * @param callback - An error-first callback that will receive the array of
+     * responses.
+     */
+    handle<Params extends JsonRpcParams, Result extends Json>(requests: (JsonRpcRequest<Params> | JsonRpcNotification<Params>)[], callback: (error: unknown, responses: JsonRpcResponse<Result>[]) => void): void;
+    /**
+     * Handle a JSON-RPC request, and return a response.
+     *
+     * @param request - The JSON-RPC request to handle.
+     * @returns The JSON-RPC response.
+     */
+    handle<Params extends JsonRpcParams, Result extends Json>(request: JsonRpcRequest<Params>): Promise<JsonRpcResponse<Result>>;
+    /**
+     * Handle a JSON-RPC notification.
+     *
+     * @param notification - The notification to handle.
+     */
+    handle<Params extends JsonRpcParams>(notification: JsonRpcNotification<Params>): Promise<void>;
+    /**
+     * Handle an array of JSON-RPC requests and/or notifications, and return an
+     * array of responses to any included requests.
+     *
+     * @param request - The JSON-RPC requests to handle.
+     * @returns An array of JSON-RPC responses.
+     */
+    handle<Params extends JsonRpcParams, Result extends Json>(requests: (JsonRpcRequest<Params> | JsonRpcNotification<Params>)[]): Promise<JsonRpcResponse<Result>[]>;
+    /**
+     * Returns this engine as a middleware function that can be pushed to other
+     * engines.
+     *
+     * @returns This engine as a middleware function.
+     */
+    asMiddleware(): JsonRpcMiddleware<JsonRpcParams, Json>;
+    /**
+     * A promise-wrapped _handle.
+     *
+     * @param request - The JSON-RPC request.
+     * @returns The JSON-RPC response.
+     */
+    private _promiseHandle;
+}
+export {};
+//# sourceMappingURL=JsonRpcEngine.d.ts.map

package/dist/JsonRpcEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonRpcEngine.d.ts","sourceRoot":"","sources":["../src/JsonRpcEngine.ts"],"names":[],"mappings":"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"}