comms

Documentation

Overview

Package comms implement the back-end (kernel) protocol over "Custom Messages" used to communicate with the front-end.

This is the counter-part to the `websocket` package, which implements (in javascript) the front-end side.

See documentation in `gonb/docs/FrontEndCommunication.md` with a diagram and description of what is going on.

Index

• Constants
• type State
  • func New() *State
  • func (s *State) Close(msg kernel.Message) error
  • func (s *State) HandleMsg(msg kernel.Message) (err error)
  • func (s *State) HandleOpen(msg kernel.Message) (err error)
  • func (s *State) InstallWebSocket(msg kernel.Message) error
  • func (s *State) ProgramFinished()
  • func (s *State) ProgramReadValueRequest(address string)
  • func (s *State) ProgramSendValueRequest(address string, value any)
  • func (s *State) ProgramStart(exec *jpyexec.Executor)
  • func (s *State) ProgramSubscribeRequest(address string)
  • func (s *State) ProgramUnsubscribeRequest(address string)
  • func (s *State) Send(msg kernel.Message, address string, value any) error
  • func (s *State) SendHeartbeatAndWait(msg kernel.Message, timeout time.Duration) (heartbeat bool, err error)

Constants

const (
	// CommOpenAckAddress is messaged in acknowledgement to a "comm_open" message.
	CommOpenAckAddress = "#comm_open_ack"

	// HeartbeatPingAddress is a protocol private message address used as heartbeat request.
	HeartbeatPingAddress = "#heartbeat/ping"

	// HeartbeatPongAddress is a protocol private message address used as heartbeat reply.
	HeartbeatPongAddress = "#heartbeat/pong"
)

const (
	HeartbeatTimeout          = 500 * time.Millisecond
	HeartbeatRequestThreshold = 1 * time.Second

	WaitForConnectionTimeout = 3 * time.Second
)

Types

type State

type State struct {

	// IsWebSocketInstalled indicates if the Javascript that runs a WebSocket that connects to JupyterServer
	// (and through that to GoNB) is installed in the front-end.
	// This is required for widgets to work: that's how they exchange update information.
	// Notice that having it installed doesn't mean yet the connection was established back -- that's what happens
	// usually, but it may take some cycles (or fail for any reason).
	IsWebSocketInstalled bool

	// TransientDisplayId is where javascript code was installed as a transient "display data".
	// It is randomly created when the websocket is installed.
	// The "transient" cell itself can be cleared after connection is established, to make sure the javascript
	// code is not saved.
	TransientDisplayId string

	// Opened indicates whether "comm_open" message has already been received.
	Opened bool

	// CommId created when the channel is opened from the front-end.
	CommId string

	// LastMsgTime is used to condition the need of a heartbeat, to access if the connection is still alive.
	LastMsgTime time.Time

	// HeartbeatPongLatch is triggered when we receive a heartbeat reply ("pong"), or when it times out.
	// A true value means it got the heartbeat, false means it didn't.
	// It is recreated everytime a HeartbeatPing is sent.
	HeartbeatPongLatch *common.LatchWithValue[bool]

	// AddressSubscriptions by the program being executed. Needs to be reset at every program
	// execution.
	AddressSubscriptions common.Set[string]

	// ProgramExecutor is a reference to the executor of the user's program (current cell).
	// It is used to dispatch comms coming from the front-end to the program.
	// This is set at the start of every cell execution, and reset to nil when the execution finishes.
	ProgramExecutor *jpyexec.Executor

	// ProgramExecMsg is the kernel.Message used to start the program.
	// This is set at the start of every cell execution, and reset to nil when the execution finishes.
	ProgramExecMsg kernel.Message

	// LogWebsocket controls whether to turn verbose logging (on the Javascript console) of the
	// WebSocket Javascript library, when it is installed.
	LogWebSocket bool
	// contains filtered or unexported fields
}

State for comms protocol. There is a singleton for the kernel, owned by goexec.State.

func New

func New() *State

New creates and initializes an empty comms.State.

func (*State) Close

func (s *State) Close(msg kernel.Message) error

Close connection with front-end. If `msg != nil`, It sends a "comm_close" message.

func (*State) HandleMsg

func (s *State) HandleMsg(msg kernel.Message) (err error)

HandleMsg is called by the dispatcher whenever a new `comm_msg` arrives from the front-end. It filters out messages with the wrong `comm_id`, handles protocol messages (heartbeat) and routes other messages.

func (*State) HandleOpen

func (s *State) HandleOpen(msg kernel.Message) (err error)

HandleOpen message, with `msg_type` set to "comm_open".

If message is incomplete, or apparently not addressed to us, it returns nil (no error) but also doesn't set communications as opened.

func (*State) InstallWebSocket

func (s *State) InstallWebSocket(msg kernel.Message) error

InstallWebSocket in the front-end, if not already installed. In the browser this is materialized as a global `gonb_comm` object, that handles communication.

If it is supposedly installed, but there has been no communication > `HeartbeatRequestThreshold` (~ 1 second), it probes with a heartbeat "ping" to check.

To install it sends a javascript is output as a transient output, so it's not saved.

If it has already been installed, this does nothing.

func (*State) ProgramFinished

func (s *State) ProgramFinished()

ProgramFinished is called when the program (cell execution) finishes.

func (*State) ProgramReadValueRequest

func (s *State) ProgramReadValueRequest(address string)

ProgramReadValueRequest handler, it implements jpyexec.CommsHandler. It sends a message with a request to read the value from the address to the front-end.

This only works if there is a `SyncedVariable` or something similar listening to the address on the front-end.

It also tries to install the WebSocket, if not yet installed.

func (*State) ProgramSendValueRequest

func (s *State) ProgramSendValueRequest(address string, value any)

ProgramSendValueRequest handler, it implements jpyexec.CommsHandler. It sends a value to the front-end.

It also tries to install the WebSocket, if not yet installed.

func (*State) ProgramStart

func (s *State) ProgramStart(exec *jpyexec.Executor)

ProgramStart is called each time a program is being executed (the contents of a cell), which is configured to use named pipes (for front-end communication/widgets).

func (*State) ProgramSubscribeRequest

func (s *State) ProgramSubscribeRequest(address string)

ProgramSubscribeRequest handler, it implements jpyexec.CommsHandler. It subscribes the program to receive updates on the given address.

It also tries to install the WebSocket, if not yet installed.

func (*State) ProgramUnsubscribeRequest

func (s *State) ProgramUnsubscribeRequest(address string)

ProgramUnsubscribeRequest handler, it implements jpyexec.CommsHandler. It unsubscribes the program to receive updates on the given address.

It also tries to install the WebSocket, if not yet installed.

func (*State) Send

func (s *State) Send(msg kernel.Message, address string, value any) error

Send value to the given address in the front-end. This, along with subscribe, is the basic communication operation with the front-end. The value will be converted to JSON before being sent.

func (*State) SendHeartbeatAndWait

func (s *State) SendHeartbeatAndWait(msg kernel.Message, timeout time.Duration) (heartbeat bool, err error)

SendHeartbeatAndWait sends a heartbeat request (ping) and waits for a reply within the given timeout. Returns true if a heartbeat was replied (pong) back, or false if it timed out. It returns an error if it failed to sendData the heartbeat message.