Skip to contents

Add a handler to a WebSocket message

Source: R/api_handlers.R
api_message.Rd

WebSockets is a bidirectional communication channel that can be established at the request of the client. While websocket communication is not really part of a standard REST api, it has many uses and can easily be used together with one.

Usage

api_message(api, handler)

Arguments

api

A plumber2 api object to add the handler to

handler

A function conforming to the specifications laid out in Details

Value

This functions return the api object allowing for easy chaining with the pipe

Details

A handler for a websocket message is much simpler than for requests in general since it doesn't have to concern itself with methods, paths, and responses. Any message handler registered will get called in sequence when a websocket message is recieved from a client. Still, a few expectations apply

Handler Arguments

The handler can take any of the following arguments:

  • message: Either a raw vector if the message recieved is in binary form or a single string, giving the message sent from the client

  • server: The Plumber2 object representing your server implementation

  • client_id: A string uniquely identifying the session the request comes from

  • request: The request that was initially used to establish the websocket connection with the client as a reqres::Request object

Handler Return Value

It is not expected that a websocket message sends a response and thus the handler is not required to do anything like that. However, if the handler returns either a raw vector or a single string it is taken as a signal to send this back to the client. Any other return value is silently ignored.