[experimental] A JSON-RPC 2.0 HTTP transport implementation (#1195)

# Summary

This is a cross-environment implementation of a basic JSON-RPC 2.0 transport. It implements the interface required by `@solana/rpc-core`, and as such is the last piece needed to be able to make an actual RPC request:

# Test Plan

```ts
const transport = createJsonRpcTransport({ url: 'https://api.devnet.solana.com' });
const blockHeight = await rpc.getBlockHeight(transport, { commitment: 'confirmed' });
console.log('blockHeight', blockHeight);
```

Author: steveluscher

packages/rpc-transport/package.json

@@ -61,6 +61,7 @@
         "@swc/core": "^1.3.18",
         "@swc/jest": "^0.2.23",
         "@types/jest": "^29.2.3",
+        "@types/node-fetch": "2",
         "@typescript-eslint/eslint-plugin": "^5.43.0",
         "@typescript-eslint/parser": "^5.43.0",
         "agadoo": "^2.0.0",
@@ -71,6 +72,7 @@
         "eslint-plugin-sort-keys-fix": "^1.1.2",
         "jest": "^29.3.1",
         "jest-environment-jsdom": "^29.3.1",
+        "jest-fetch-mock": "^3.0.3",
         "jest-runner-eslint": "^1.1.0",
         "jest-runner-prettier": "^1.0.0",
         "postcss": "^8.4.12",
@@ -89,5 +91,9 @@
                 "path": "./dist/index*.js"
             }
         ]
+    },
+    "dependencies": {
+        "@solana/fetch-impl-browser": "workspace:*",
+        "node-fetch": "^2.6.7"
     }
 }

packages/rpc-transport/src/__tests__/http-transport-test.ts

@@ -0,0 +1,66 @@
+import { makeHttpRequest } from '../http-request';
+import { SolanaHttpError } from '../http-request-errors';
+
+describe('makeHttpRequest', () => {
+    describe('when the endpoint returns a non-200 status code', () => {
+        beforeEach(() => {
+            fetchMock.once('', { status: 404, statusText: 'We looked everywhere' });
+        });
+        it('throws HTTP errors', async () => {
+            expect.assertions(3);
+            const requestPromise = makeHttpRequest({ payload: 123, url: 'fake://url' });
+            await expect(requestPromise).rejects.toThrow(SolanaHttpError);
+            await expect(requestPromise).rejects.toThrow(/We looked everywhere/);
+            await expect(requestPromise).rejects.toMatchObject({ statusCode: 404 });
+        });
+    });
+    describe('when the transport fatals', () => {
+        beforeEach(() => {
+            fetchMock.mockReject(new TypeError('Failed to fetch'));
+        });
+        it('passes the exception through', async () => {
+            expect.assertions(1);
+            await expect(makeHttpRequest({ payload: 123, url: 'fake://url' })).rejects.toThrow(
+                new TypeError('Failed to fetch')
+            );
+        });
+    });
+    describe('when the endpoint returns a well-formed JSON response', () => {
+        beforeEach(() => {
+            fetchMock.once(JSON.stringify({ ok: true }));
+        });
+        it('calls fetch with the specified URL', () => {
+            makeHttpRequest({ payload: 123, url: 'fake://url' });
+            expect(fetchMock).toHaveBeenCalledWith('fake://url', expect.anything());
+        });
+        it('sets the `body` to a stringfied version of the payload', () => {
+            makeHttpRequest({ payload: { ok: true }, url: 'fake://url' });
+            expect(fetchMock).toHaveBeenCalledWith(
+                expect.anything(),
+                expect.objectContaining({
+                    body: JSON.stringify({ ok: true }),
+                })
+            );
+        });
+        it('sets the content type header to `application/json`', () => {
+            makeHttpRequest({ payload: 123, url: 'fake://url' });
+            expect(fetchMock).toHaveBeenCalledWith(
+                expect.anything(),
+                expect.objectContaining({
+                    headers: expect.objectContaining({
+                        'Content-type': 'application/json',
+                    }),
+                })
+            );
+        });
+        it('sets the `method` to `POST`', () => {
+            makeHttpRequest({ payload: 123, url: 'fake://url' });
+            expect(fetchMock).toHaveBeenCalledWith(
+                expect.anything(),
+                expect.objectContaining({
+                    method: 'POST',
+                })
+            );
+        });
+    });
+});

packages/rpc-transport/src/__tests__/json-rpc-message-test.ts

@@ -0,0 +1,18 @@
+import { createJsonRpcMessage } from '../json-rpc-message';
+
+describe('createJsonRpcMessage', () => {
+    it('auto-increments ids with each new message', () => {
+        const { id: firstId } = createJsonRpcMessage('foo', 'bar');
+        const { id: secondId } = createJsonRpcMessage('foo', 'bar');
+        expect(secondId - firstId).toBe(1);
+    });
+    it('returns a well-formed JSON-RPC 2.0 message', () => {
+        const params = [1, 2, 3];
+        expect(createJsonRpcMessage('someMethod', params)).toStrictEqual({
+            id: expect.any(Number),
+            jsonrpc: '2.0',
+            method: 'someMethod',
+            params,
+        });
+    });
+});

packages/rpc-transport/src/__tests__/json-rpc-transport-test.ts

@@ -0,0 +1,26 @@
+import { IJsonRpcTransport } from '..';
+import { SolanaJsonRpcError } from '../json-rpc-errors';
+import { createJsonRpcTransport } from '../json-rpc-transport';
+
+import fetchMock from 'jest-fetch-mock';
+
+describe('JSON-RPC 2.0 transport', () => {
+    let transport: IJsonRpcTransport;
+    beforeEach(() => {
+        transport = createJsonRpcTransport({ url: 'fake://url' });
+    });
+    it('returns results from a JSON-RPC 2.0 endpoint', async () => {
+        expect.assertions(1);
+        fetchMock.once(JSON.stringify({ result: 123 }));
+        const result = await transport.send('someMethod', undefined);
+        expect(result).toBe(123);
+    });
+    it('throws errors from a JSON-RPC 2.0 endpoint', async () => {
+        expect.assertions(3);
+        fetchMock.once(JSON.stringify({ error: { code: 123, data: 'abc', message: 'o no' } }));
+        const sendPromise = transport.send('someMethod', undefined);
+        await expect(sendPromise).rejects.toThrow(SolanaJsonRpcError);
+        await expect(sendPromise).rejects.toThrow(/o no/);
+        await expect(sendPromise).rejects.toMatchObject({ code: 123, data: 'abc' });
+    });
+});

packages/rpc-transport/src/http-request-errors.ts

@@ -0,0 +1,16 @@
+type SolanaHttpErrorDetails = Readonly<{
+    statusCode: number;
+    message: string;
+}>;
+
+export class SolanaHttpError extends Error {
+    readonly statusCode: number;
+    constructor(details: SolanaHttpErrorDetails) {
+        super(`HTTP error (${details.statusCode}): ${details.message}`);
+        Error.captureStackTrace(this, this.constructor);
+        this.statusCode = details.statusCode;
+    }
+    get name() {
+        return 'SolanaHttpError';
+    }
+}

packages/rpc-transport/src/http-request.ts

@@ -0,0 +1,32 @@
+import fetchImplBrowser from '@solana/fetch-impl-browser';
+import { SolanaHttpError } from './http-request-errors';
+
+import fetchImplNode from 'node-fetch';
+
+type Config = Readonly<{
+    payload: unknown;
+    url: string;
+}>;
+
+export async function makeHttpRequest<TResponse>({ payload, url }: Config): Promise<TResponse> {
+    const requestInfo = {
+        body: JSON.stringify(payload),
+        headers: {
+            'Content-type': 'application/json',
+        },
+        method: 'POST',
+    };
+    let response;
+    if (__BROWSER__ || __REACTNATIVE__) {
+        response = await fetchImplBrowser(url, requestInfo);
+    } else {
+        response = await fetchImplNode(url, requestInfo);
+    }
+    if (!response.ok) {
+        throw new SolanaHttpError({
+            message: response.statusText,
+            statusCode: response.status,
+        });
+    }
+    return await response.json();
+}

packages/rpc-transport/src/index.ts

@@ -1,5 +1,7 @@
+import { createJsonRpcTransport } from './json-rpc-transport';
+
 export interface IJsonRpcTransport {
     send<TParams, TResponse>(method: string, params: TParams): Promise<TResponse>;
 }
 
-export {};
+export { createJsonRpcTransport };

packages/rpc-transport/src/json-rpc-errors.ts

@@ -0,0 +1,19 @@
+type SolanaJsonRpcErrorDetails = Readonly<{
+    code: number;
+    data?: unknown;
+    message: string;
+}>;
+
+export class SolanaJsonRpcError extends Error {
+    readonly code: number;
+    readonly data: unknown;
+    constructor(details: SolanaJsonRpcErrorDetails) {
+        super(`JSON-RPC 2.0 error (${details.code}): ${details.message}`);
+        Error.captureStackTrace(this, this.constructor);
+        this.code = details.code;
+        this.data = details.data;
+    }
+    get name() {
+        return 'SolanaJsonRpcError';
+    }
+}

packages/rpc-transport/src/json-rpc-message.ts

@@ -0,0 +1,15 @@
+let _nextMessageId = 0;
+function getNextMessageId() {
+    const id = _nextMessageId;
+    _nextMessageId = (_nextMessageId + 1) % Number.MAX_SAFE_INTEGER;
+    return id;
+}
+
+export function createJsonRpcMessage<TParams>(method: string, params: TParams) {
+    return {
+        id: getNextMessageId(),
+        jsonrpc: '2.0',
+        method,
+        params,
+    };
+}

packages/rpc-transport/src/json-rpc-transport.ts

@@ -0,0 +1,29 @@
+import { IJsonRpcTransport } from '.';
+import { makeHttpRequest } from './http-request';
+import { SolanaJsonRpcError } from './json-rpc-errors';
+import { createJsonRpcMessage } from './json-rpc-message';
+
+type Config = Readonly<{
+    url: string;
+}>;
+
+type JsonRpcResponse<TResponse> = Readonly<
+    { result: TResponse } | { error: { code: number; message: string; data?: unknown } }
+>;
+
+export function createJsonRpcTransport({ url }: Config): IJsonRpcTransport {
+    return {
+        async send<TParams, TResponse>(method: string, params: TParams): Promise<TResponse> {
+            const jsonRpcMessage = createJsonRpcMessage(method, params);
+            const response = await makeHttpRequest<JsonRpcResponse<TResponse>>({
+                payload: jsonRpcMessage,
+                url,
+            });
+            if ('error' in response) {
+                throw new SolanaJsonRpcError(response.error);
+            } else {
+                return response.result as TResponse;
+            }
+        },
+    };
+}