postMessage RPC

RPC utilities using postMessage

Installation

npm install @ceramicnetwork/rpc-postmessage

Usage

import { createNamespaceClient, createNamespaceServer } from '@ceramicnetwork/rpc-postmessage'

type Methods = {
  foo: { result: string }
}

const server = createNamespaceServer<Methods>({
  target: window, // Listens to requests on window
  namespace: 'test',
  methods: { foo: () => 'bar' },
}).subscribe()

// Sends requests and receives responses on window
const transport = createPostMessageTransport(window, window, { postMessageArguments: ['*'] })

const client = createNamespaceClient(transport, 'test')
await client.request('foo') // 'bar'

// Stop server when done
server.unsubscribe()

Types

RequestPayload

Uses RPCMethods and RPCRequest

type RequestPayload<Message, Methods extends RPCMethods, K extends keyof Methods> = {
  type: 'request'
  message: Message
  request: RPCRequest<Methods, K>
}

HandledPayload

Uses RPCMethods, RPCRequest and RPCResponse

type HandledPayload<Message, Methods extends RPCMethods, K extends keyof Methods> = {
  type: 'handled'
  message: Message
  request: RPCRequest<Methods, K>
  response: RPCResponse<Methods, K> | null
}

ServerOptions

Uses RPCMethods, HandlerMethods and HandlerOptions

type ServerOptions<Context, Methods extends RPCMethods> = HandlerOptions<Context, Methods> & {
  target: PostMessageTarget
  methods: HandlerMethods<Context, Methods>
}

NamespaceServerOptions

type NamespaceServerOptions<
  Methods extends RPCMethods,
  Namespace extends string = string,
  Message = IncomingMessage<Wrapped<RPCRequest<Methods, keyof Methods>, Namespace>>
> = ServerOptions<Message, Methods> & {
  namespace: Namespace
  filter?: string | Array<string> | MessageFilter
}

NamespaceClientTransport

type NamespaceClientTransport<
  Methods extends RPCMethods,
  Namespace extends string,
  Incoming = IncomingMessage<Wrapped<RPCResponse<Methods, keyof Methods>, Namespace>>,
  Outgoing = Wrapped<RPCRequest<Methods, keyof Methods>, Namespace>
> = TransportSubject<Incoming, Outgoing>

APIs

serve()

Receives requests and sends responses on the provided target

Type parameters

1. Methods extends RPCMethods

Arguments

1. options: ServerOptions<null, Methods>

Returns Subscription

createNamespaceRequestHandlerOperator()

Type parameters

1. Methods extends RPCMethods
2. Namespace extends string = string
3. Message = IncomingMessage<Wrapped<RPCRequest<Methods, keyof Methods>, Namespace>>

Arguments

1. methods: HandlerMethods<Message, Methods>
2. namespace: Namespace
3. options?: HandlerOptions<Message, Methods> = {}

Returns OperatorFunction<Message, HandledPayload<Message, Methods, keyof Methods>>

createNamespaceServer()

Type parameters

1. Methods extends RPCMethods
2. Namespace extends string = string
3. Request = Wrapped<RPCRequest<Methods, keyof Methods>, Namespace>

Arguments

1. options: NamespaceServerOptions<Methods, Namespace, IncomingMessage<Request>>

Returns Observable<HandledPayload<IncomingMessage<Request>, Methods, keyof Methods>>

createNamespaceSendRequest()

Type parameters

1. Methods extends RPCMethods
2. Namespace extends string = string

Arguments

1. transport: NamespaceClientTransport<Methods, Namespace>
2. namespace: Namespace
3. options?: UnwrapObservableOptions

Returns SendRequestFunc<Methods>

createNamespaceClient()

Type parameters

1. Methods extends RPCMethods
2. Namespace extends string = string

Arguments

1. transport: NamespaceClientTransport<Methods, Namespace>
2. namespace: Namespace
3. options?: UnwrapObservableOptions

Returns RPCClient<Methods>

License

Apache-2.0 OR MIT