Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Client<Ctx>

Type parameters

  • Ctx: unknown = null

Hierarchy

  • Client

Index

Constructors

constructor

  • new Client<Ctx>(): Client<Ctx>
  • Type parameters

    • Ctx: unknown = null

      context, passed to various callbacks, specified when calling open

    Returns Client<Ctx>

Properties

connectionState

connectionState: ConnectionState

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

Methods

close

  • close(): void
  • Closes the connection.

    • open must have been called before calling this method
    • If we haven't connected yet, open callback will be called with an error
    • If there's an open WebSocket connection it will be closed
    • Any open channels will be closed
      • Does not clear openChannel requests
      • If a channel never opened, its open channel callback will be called with an error
      • Otherwise returned cleanup callback is called

    Returns void

destroy

  • destroy(): void
  • Destroy 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.

    Returns void

getConnectionMetadata

  • Gets the current connection metadata used by the WebSocket, or null if the WebSocket is not present.

    Returns null | GovalMetadata

open

  • 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
      };
    });
    

    Parameters

    Returns void

openChannel

  • Opens a channel for a service and returns a function to close the channel.

    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.

    Parameters

    Returns () => void

    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);
      };
    });
    
      • (): void
      • Returns void

setDebugFunc

  • setDebugFunc(debugFunc: (log: DebugLog) => void): void

setUnrecoverableErrorHandler

  • setUnrecoverableErrorHandler(onUnrecoverableError: (e: Error) => void): void
  • Set a function to handle unrecoverable error

    Unrecoverable errors are internal errors or invariance errors caused by the user mis-using the client.

    Parameters

    • onUnrecoverableError: (e: Error) => void
        • (e: Error): void
        • Parameters

          • e: Error

          Returns void

    Returns void

Generated using TypeDoc