Indicates the current state of the connection with the container.
This will only be DISCONNECTED if open has not been called
or the client closed permanently. Otherwise it'll be
CONNECTED or CONNECTING
Closes the connection.
open must have been called before calling this methodDestroy closes the connection, so all the rules of close apply here.
The only difference is that destroy renders the client unsuable afterwards.
It will also cleanup all saved openChannel calls freeing the callbacks and
avoiding leaks.
Gets the current connection metadata used by the WebSocket, or null if the WebSocket is not present.
Starts connecting to the server and and opens channel 0
See https://protodoc.turbio.repl.co/protov2 from more protocol specific info.
Every client connected automatically "has" channel 0 listen to global events. Any time the client connects it will call callback with channel 0 so you can use it. Please refrain from using channel 0 to open channels and use Client.openChannel instead.
This function follows similar semantics to Client.openChannel. The only difference is the first parameter which specifies options around the connection in addition to a context that is passed to various callbacks. It also does not return a close function, instead you can use Client.close.
Usage:
client.open({ context, fetchConnectionMetadata }, function onOpen({
channel,
context,
}) {
if (!channel) {
// Closed before ever connecting. Due to `client.close` being called
// or an unrecoverable, that can be handled by setting `client.setUnrecoverableError`
return;
}
// The client is now connected (or reconnected in the event that it encountered an unexpected disconnect)
// `channel` here is channel0 (more info at http://protodoc.turbio.repl.co/protov2)
// - send commands using `channel.send`
// - listen for commands using `channel.onCommand(cmd => ...)`
return function cleanup({ willReconnect }) {
// The client was closed and might reconnect if it was closed unexpectedly
};
});
Read opening channels section in the protocol documentation for protocol specific information.
When the client connects, and the channel opens, the open callback is called with the channel. As you should already know, you can use the channel to send commands and listen on incoming commands. Once the client disconnects the channel is closed and is rendered un-usable (using it will throw an error) and you must wait for a new channel to be passed to the callback upon reconnection.
The channel will keep reopening upon client reconnects so long as you don't call the close channel function.
You can return an optional clean up function from the open callback to be used as a signal for the channel closing, regardless of whether it is going to reconnect or not. The cleanup function will be called with ChannelCloseReason which contians some useful information about reconnection and why we closed.
If Client.close is called, it will close all channels and they won't reconnect. However,
if you Client.open again in the future, all previously opened channels will re-open, unless
the returned close channel function was called. Client.destroy will free up all openChannel
calls but the client is unusable going forward.
Options for the channel
The open callback
A function to close the channel
Usage:
// See docs for exec service here https://protodoc.turbio.repl.co/services#exec
const closeChannel = client.openChannel({ service: 'exec' }, function open({
error,
channel,
context,
}) {
if (error) {
return;
}
channel.onCommand((cmd) => {
if (cmd.output) {
terminal.write(cmd.output);
}
});
const intervalId = setInterval(() => {
channel.send({
exec: { args: ['echo', 'hello', context.user.name] }
blocking: true,
});
}, 100);
return function cleanup() {
clearInterval(intervalId);
};
});
Set a function to handle unrecoverable error
Unrecoverable errors are internal errors or invariance errors caused by the user mis-using the client.
Generated using TypeDoc
context, passed to various callbacks, specified when calling open