IPC API library

[aesedepece]

The IPC API library is an IPC server that wraps and exposes backend methods to the frontend.

[aesedepece]

@kronolynx 's research on IPC is in #23

[aesedepece]

Whoever gets assigned this story will likely need to:

1. Play with @kronolynx snippet in Assess backend <> frontend communication solutions for Electron #23 to master how IPC works in Electron and how to use it both in the main process (NodeJS) and the renderer process (web context).
2. Find the right place in the project directories for both sides of the IPC API.
3. Implement a ping/pong method in the IPC API.
4. Assess if testing IPC makes sense at all. If it does, guess how to and write tests for (3).
5. Continue with Expose wallet creation methods #28 and Expose wallet unlocking methods #29 once Keypair and wallet generation (backend only) #19 and Basic wallet functionality (backend only) #21 maturate (after Crypto module #31 gets merged)

[aesedepece]

This is being worked by @mmartinbar in her ipc branch.

[aesedepece]

As per latest design, API methods are implemented in the backend by exporting them inside the /handlers folder, which shall be eventually renamed to /api.

Those methods need to comply with the ChanDesc type.

[aesedepece]

Synchronous model

Main process implementation

ipcMain.on(IPC_SYNC_CHAN_NAME, async (event: any, args: any) => {
  // Reconstruct request from serialized message
  const syncRequest: ChanRequest = JSON.parse(args)
  // Check request validity
  if (!isValidChanRequest(syncRequest)) throw new Error("Malformed IPC request")
  // Check if method is supported
  if (syncRequest.method in methods) {
    // Call matching method handler to get specific response
    const responseMessage = await channels[chanReq.method](chanReq.params)
    // Wrap response into a generic protocol response
    const response = buildChanResponse(ChanResCode.Ok, chanReq.id, responseMessage)
  } else {
    // Wrap error message into a generic protocol response
    const response = buildChanResponse(ChanResCode.ErrUnknownMethod, chanReq.id, `Unsupported method: ${syncRequest.method}`)
  }
  // Return the wrapped response
  event.returnValue = response
})

Renderer process implementation

None

Renderer process usage

// Construct a new request
const syncRequest = buildChanRequest("ping")
// Send request and wait for response
const response = ipcRenderer.sendSync(IPC_SYNC_CHAN_NAME, syncRequest)

Asynchronous model

Main process implementation

ipcMain.on(IPC_ASYNC_CHAN_NAME, async (event: any, args: any) => {
  // Reconstruct request from serialized message
  const syncRequest: ChanRequest = JSON.parse(args)
  // Check request validity
  if (!isValidChanRequest(syncRequest)) throw new Error("Malformed IPC request")
  // Check if method is supported
  if (syncRequest.method in methods) {
    // Call matching method handler to get specific response
    const responseMessage = await channels[chanReq.method](chanReq.params)
    // Wrap response into a generic protocol response
    const response = buildChanResponse(ChanResCode.Ok, chanReq.id, responseMessage)
  } else {
    // Wrap error message into a generic protocol response
    const response = buildChanResponse(ChanResCode.ErrUnknownMethod, chanReq.id, `Unsupported method: ${syncRequest.method}`)
  }
  // Send the wrapped response back
  sendAsyncMessage(event.sender, JSON.stringify(response))
})

Renderer process implementation

// Holds promises for each pending request
const pendingRequests = {}

// Keeps a count of sent requests
let requestsCount = 0

// Creates new requests
const buildChanRequest = (method: string, params?: any): ChanRequest => {
  return { id: requestsCount++, method, params }
}

// Conviniently wraps all the IPC and request/response correlation magic
const asyncSend = async (asyncRequest: ChanRequest, timeout = 5000): ChanResponse => {
  // Create a promise for each message
  const promise = new Promise((resolve, reject) => {
    // Create the timeout and get a reference to the timer
    const timer = setTimeout(() => {
      const error = new Error(`Timed out after ${timeout}ms`)
      error.name = "TimeoutError"
      reject(error)
    }, timeout)
    // Store the resolver, rejecter and timer references
    pendingRequests[asyncRequest.id] = [resolve, reject, timer]
  })
  // Send the asynchronous request
  ipcRenderer.send(IPC_ASYNC_CHAN_NAME, JSON.stringify(asyncRequest))
  // Return the promise
  return promise
}

// Only response entry point in the renderer process
ipcRenderer.on(IPC_ASYNC_CHAN_NAME, async (event: any, args: any) => {
  // Reconstruct request from serialized message
  const asyncResponse: ChanResponse = JSON.parse(args)
  // Check response validity
  if (!isValidChanResponse(asyncResponse)) throw new Error("Malformed IPC response")
  // Find request for which this is a response 
  if (asyncResponse.id in pendingRequests) {
    const [resolve, reject, timer] = pendingRequests[asyncResponse.id]
    // As we got a response, let's unset the timeout
    clearTimeout(timer)
    // Resolve or reject depending on success or error
    if (asyncResponse.error) {
      reject(asyncResponse.error)
    } else {
      resolve(asyncResponse.result)
    }
  } else {
    // Ignore it? This is probably a late reponse (arrived after timing out)
  }
})

Renderer process usage

Naive approach

const asyncRequest: ChanRequest = buildChanRequest("ping")
const asyncResponse = await asyncSend(asyncRequest)

Responsible approach

const asyncRequest: ChanRequest = buildChanRequest("ping")
asyncSend(asyncRequest)
  .then((response) => {
    console.log("Backend responded", response)
  })
  .catch((error) => {
    if (error.name === "TimeoutError") {
      console.error("Backend timed out", error)
    } else {
      console.error(error)
    }
  })

Using then/catch allows the renderer process to update the UI according to whatever happens with the request.

[aesedepece]

Today we had an informal yet very interesting discussion on how to test our IPC API.

These were our conclusions:

• We SHALL NOT create integration or functional tests with the real Electron IPC in place. It's overkill.
• We MUST abstract/detach renderer API methods from the actual IPC calls. This gives us the chance to substitute ipcRenderer with a mock transport and unit-test if these methods construct the messages as expected.
• We MUST abstract/detach main API handlers from the actual IPC calls. This gives us the chance to substitute ipcMain with a mock transport and unit-test if the handlers construct the responses as expected.
• We MAY create integration tests covering the whole lifetime of a renderer<>main request/response. This is done by using a pass-through transport directly connecting the renderer to the main process. Yes, this can be done in the tests only because we are cheating: we're running browser code (the renderer API methods) in a NodeJS context 😛.