feat(IPC): Add client and server classes

Author: nokome

src/base/Client.test.ts

@@ -0,0 +1,45 @@
+import Client from './Client'
+import Request from './Request';
+import Response from './Response';
+
+/**
+ * Simple test client that implements the
+ * necessary `send` method to echo back the
+ * called method and parameters.
+ */
+class TestClient extends Client {
+  send(request: Request) {
+    const { id, method, params } = request
+    const response = new Response(id, { method, params })
+    this.receive(response)
+  }
+}
+
+test('client', async () => {
+  const client = new TestClient()
+
+  expect(await client.capabilities()).toEqual({
+    method: 'capabilities',
+    params: []
+  })
+
+  expect(await client.convert('{}')).toEqual({
+    method: 'convert',
+    params: ['{}', 'json', 'json']
+  })
+
+  expect(await client.compile({})).toEqual({
+    method: 'compile',
+    params: [{}, 'json']
+  })
+
+  expect(await client.build({})).toEqual({
+    method: 'build',
+    params: [{}, 'json']
+  })
+
+  expect(await client.execute({})).toEqual({
+    method: 'execute',
+    params: [{}, 'json']
+  })
+})

src/base/Client.ts

@@ -0,0 +1,99 @@
+import * as stencila from '@stencila/schema';
+import Executor, { Method, Capabilities } from './Executor';
+import Request from './Request';
+import Response from './Response';
+
+/**
+ * A base client class which acts as a proxy to a remote `Executor`.
+ *
+ * Implements aynchronous, proxy methods for `Executor` methods `compile`, `build`, `execute`, etc.
+ * Those methods send JSON-RPC requests to a `Server` that is serving the remote `Executor`.
+ */
+export default abstract class Client extends Executor {
+
+  /**
+   * A map of requests to which responses can be paired against
+   */
+  private requests: {[key: number]: (response: Request) => void } = {}
+
+  /**
+   * Call the remote `Executor`'s `capabilities` method
+   */
+  async capabilities (): Promise<Capabilities> {
+    return this.call<Capabilities>(Method.capabilities)
+  }
+
+  /**
+   * Call the remote `Executor`'s `convert` method
+   */
+  async convert (node: string | stencila.Node, from: string = 'json', to: string = 'json'): Promise<string> {
+    return this.call<string>(Method.convert, node, from, to)
+  }
+
+  /**
+   * Call the remote `Executor`'s `compile` method
+   */
+  async compile (node: string | stencila.Node, format: string = 'json'): Promise<stencila.Node> {
+    return this.call<stencila.Node>(Method.compile, node, format)
+  }
+
+  /**
+   * Call the remote `Executor`'s `build` method
+   */
+  async build (node: string | stencila.Node, format: string = 'json'): Promise<stencila.Node> {
+    return this.call<stencila.Node>(Method.build, node, format)
+  }
+
+  /**
+   * Call the remote `Executor`'s `execute` method
+   */
+  async execute (node: string | stencila.Node, format: string = 'json'): Promise<stencila.Node> {
+    return this.call<stencila.Node>(Method.execute, node, format)
+  }
+
+  /**
+   * Call a method of a remote `Executor`.
+   *
+   * @param method The name of the method
+   * @param args Any method arguments
+   */
+  private async call<Type> (method: Method, ...args: Array<any>): Promise<Type> {
+    const request = new Request(method, args)
+    const promise = new Promise<Type>((resolve, reject) => {
+      this.requests[request.id] = (response: Response) => {
+        if (response.error) return reject(new Error(response.error.message))
+        resolve(response.result)
+      }
+    })
+    this.send(request)
+    return promise
+  }
+
+  /**
+   * Send a request to the server.
+   *
+   * This method must be overriden by derived client classes to
+   * send the request over the transport used by that class.
+   *
+   * @param request The JSON-RPC request
+   */
+  protected abstract send (request: Request): void
+
+  /**
+   * Receive a response from the server.
+   *
+   * Usually called asynchronously via the `send` method of a derived class
+   * when a response is returned. Uses the `id` of the response to match it to the corresponding
+   * request and resolve it's promise.
+   *
+   * @param response The JSON-RPC response
+   */
+  protected receive (response: string | Response): void {
+    if (typeof response === 'string') response = JSON.parse(response) as Response
+    if (response.id < 0) throw new Error(`Response is missing id: ${response}`)
+    const resolve = this.requests[response.id]
+    if (resolve === undefined) throw new Error(`No request found for response with id: ${response.id}`)
+    resolve(response)
+    delete this.requests[response.id]
+  }
+}

src/base/Error.ts

@@ -0,0 +1,32 @@
+/**
+ * A JSON-RPC 2.0 response error
+ *
+ * @see {@link https://www.jsonrpc.org/specification#error_object}
+ */
+export default class JsonRpcError {
+  /**
+   * A Number that indicates the error type that occurred.
+   * This MUST be an integer.
+   */
+  code: number
+
+  /**
+   * A String providing a short description of the error.
+   * The message SHOULD be limited to a concise single sentence.
+   */
+  message: string
+
+  /**
+   * A Primitive or Structured value that contains additional information about the error.
+   * This may be omitted.
+   * The value of this member is defined by the Server (e.g. detailed error information,
+   * nested errors etc.).
+   */
+  data?: any
+
+  constructor (code: number, message: string, data?: any) {
+    this.code = code
+    this.message = message
+    this.data = data
+  }
+}

src/base/Executor.ts

@@ -0,0 +1,46 @@
+import * as stencila from '@stencila/schema'
+
+export enum Method {
+  capabilities = 'capabilities',
+  convert = 'convert',
+  compile = 'compile',
+  build = 'build',
+  execute = 'execute'
+}
+
+export type Capabilities = {[key in Method]: any}
+
+/**
+ */
+export default class Executor {
+
+  /**
+   * Get the capabilities of this executor
+   */
+  async capabilities (): Promise<Capabilities> {
+    return {
+      capabilities: true,
+      convert: false,
+      compile: false,
+      build: false,
+      execute: false
+    }
+  }
+
+  async convert (node: string | stencila.Node, from: string = 'json', to: string = 'json'): Promise<string> {
+    if (typeof node === 'string') return node
+    else return JSON.stringify(node)
+  }
+
+  async compile (node: string | stencila.Node, format: string = 'json'): Promise<stencila.Node> {
+    return node
+  }
+
+  async build (node: string | stencila.Node, format: string = 'json'): Promise<stencila.Node> {
+    return node
+  }
+
+  async execute (node: string | stencila.Node, format: string = 'json'): Promise<stencila.Node> {
+    return node
+  }
+}

src/base/Request.ts

@@ -0,0 +1,49 @@
+/**
+ * A JSON-RPC 2.0 request
+ *
+ * @see {@link https://www.jsonrpc.org/specification#request_object}
+ */
+export default class Request {
+  /**
+   * A string specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
+   */
+  jsonrpc: string = '2.0'
+
+  /**
+   * An identifier established by the Client that MUST contain a string, number, or
+   * NULL value if included. If it is not included it is assumed to be a notification.
+   * The value SHOULD normally not be Null and numbers SHOULD NOT contain fractional
+   * parts. The Server MUST reply with the same value in the Response object if included.
+   * This member is used to correlate the context between the two objects.
+   */
+  id: number
+
+  /**
+   * A string containing the name of the method to be invoked.
+   * Method names that begin with the word rpc followed by a period character
+   * (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and
+   * MUST NOT be used for anything else.
+   */
+  method?: string
+
+  /**
+   * A structured value that holds the parameter values to be used during the
+   * invocation of the method.This member MAY be omitted.
+   */
+  params?: {[key: string]: any} | any[]
+
+  /**
+   * A counter for generating unique, sequential request ids.
+   *
+   * Request ids don't need to be sequential but this helps with debugging.
+   * Request ids don't need to be unique across clients.
+   */
+  static counter: number = 0
+
+  constructor (method?: string, params?: {[key: string]: any} | any[]) {
+    Request.counter += 1
+    this.id = Request.counter
+    this.method = method
+    this.params = params
+  }
+}

src/base/Response.ts

@@ -0,0 +1,40 @@
+import Error from './Error'
+
+/**
+ * A JSON-RPC 2.0 response
+ *
+ * @see {@link https://www.jsonrpc.org/specification#response_object}
+ */
+export default class Response {
+  /**
+   * A string specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
+   */
+  jsonrpc: string = '2.0'
+
+  /**
+   * This member is REQUIRED.
+   * It MUST be the same as the value of the id member in the Request Object.
+   * If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.
+   */
+  id: number
+
+  /**
+   * This member is REQUIRED on success.
+   * This member MUST NOT exist if there was an error invoking the method.
+   * The value of this member is determined by the method invoked on the Server.
+   */
+  result?: any
+
+  /**
+   * This member is REQUIRED on error.
+   * This member MUST NOT exist if there was no error triggered during invocation.
+   * The value for this member MUST be an Object as defined in section 5.1.
+   */
+  error?: Error
+
+  constructor (id: number = -1, result?: any, error?: Error) {
+    this.id = id
+    this.result = result
+    this.error = error
+  }
+}