cockpit.js: Raw Channels

cockpit.js: Raw Channels — Raw communication channels

Synopsis

At a low level Cockpit communicates with the system via messages passed
through various channels. These are usually exposed via higher level APIs,
such as the cockpit.spawn() function.
It is rare to use raw channels directly.

cockpit.channel()

channel = cockpit.channel(options)

This function creates a new channel for communication with the system.
It returns a new channel object. The options argument is a
plain object. At least the "payload" option is required, and
based on the payload type, other options may be required.

"binary"

Set to true to transfer binary payloads. Both messages
sent via channel.send()
and those received via
channel.onmessage
should be arrays of bytes, either Uint8Array or Array
depending on browser support.

"host"

The host to open the channel to. If an alternate user or port is
required it can be specified as "user@myhost:port". If no host
is specified then the correct one will be automatically selected based on the page
calling this function.

"payload"

The payload type for the channel. Only specific payload
types are supported.

"superuser"

Set to "require" to open this channel as root. If the currently
logged in user is not permitted to become root (eg: via pkexec) then the
channel will immediately be
closed with a "access-denied"
problem code.

Set to "try" to try to open the channel as root, but if that fails,
then fall back to an unprivileged channel.

The channel object returned has the following fields and methods and
events. You should call the
channel.close()
method when done with the channel.

channel.binary

Will be true for an binary channel. Will be set to false if the
channel is textual.

channel.options

The options used to open this channel. This should not be changed.

channel.valid

Will be true for an open channel. Will be set to false if the channel
closes.

channel.send()

channel.send(data)

Send a message over the channel. The contents of the message depends on the
payload type of the channel. If a binary channel, then data is expected
to be an Array of bytes or a Uint8Array. If not binary,
then the data will be converted to a string if not already a string.

channel.control()

channel.control(options)

Notify the channel to tune certain parameters on the fly. The options
is a plain javascript object, and the contents depend on the "payload"
of the channel.

One common operation is to set "command" to "done" in the
options field. To indicate that no further messages will be sent through the channel.

channel.wait()

promise = channel.wait([callback])

Returns a promise that is ready when the channel is ready, or fails if the
client closes. If a callback is specified, it is attached to the promise. The
promise will be rejected or resolved with the contents options passed to the
channel.onready and
channel.onclose events respectively.

In general it's not necessary to wait for the channel before starting to use the channel.

channel.close()

channel.close([options])

Close the channel.

If options is present it can be a plain javascript object
containing additional channel close options to send to the peer. If closing for
because of a problem, set the "problem" field to a
problem code. If options
is not an object it will be treated as a "problem".

The close event will fire.
A channel can also be closed by a peer or if the underlying transport closes.

channel.onmessage

channel.addEventListener("message", function(event, data) { ... })

An event triggered when the channel receives a message. The message is
passed as a string to the handler in the data. In the case of binary
channels data is an Uint8Array or an Array
of bytes if the former is not supported by the browser. The contents of
the message depends on the payload type of the channel.

channel.oncontrol

channel.addEventListener("control", function(event, options) { ... })

An event triggered when the channel receives an control message in the
middle of the flow. One particular use is when the command is set to
"done" then no further messages will be received in the channel.
The exact form of these messages depend on the "payload" of the
channel.

channel.onready

channel.addEventListener("ready", function(event, options) { ... })

An event triggered when the other end of the channel is ready to start processing
messages. This indicates the channel is completely open. It is possible to start
sending messages on the channel before this point.

channel.onclose

channel.addEventListener("close", function(event, options) { ... })

An event triggered when the channel closes. This can happen either because
channel.close() function was called,
or if the peer closed the channel, or the underlying transport closes.

The options will contain various close information, including a
"problem" field which will be set if the channel was closed because
of a problem.

cockpit.transport.origin

cockpit.transport.origin

The HTTP origin that is being used by the underlying channel transport. This is
read-only, you should not assign a value. If the browser supports
window.location.origin then this will be identical to that value.

cockpit.transport.host

cockpit.transport.host

The host that this transport is going to talk to by default. This is
read-only, you should not assign a value. If the value is null that means that the
transport has not been setup yet.

cockpit.transport.csrf_token

cockpit.transport.csrf_token

A cross site request forgery token for use with external channels. This becomes
valid once the connection is properly established.

cockpit.transport.options

cockpit.transport.options

Initialization options received over the underlying channel transport. These
will be empty until connection is properly established.

cockpit.transport.wait()

cockpit.transport.wait(callback)

Call the callback function once the underlying channel transport is initialized.
This will start the initialization if not already in progress or completed. If the
channel transport is already initialized, then callback will be called
immediately.

In general it's not necessary to wait for the transport before starting to open channels.

cockpit.transport.close()

cockpit.transport.close([problem])

Close the underlying channel transport. All channels open channels will close.
The problem argument should be a problem code string. If not specified
it will default to "disconnected".

cockpit.transport.filter()

Add a filter to the underlying channel transport. All incoming messages will be
passed to each of the filter callbacks that are registered. If the out
argument is equal to true then the filter will receive outgoing messages
that being sent on the underlying channel transport.

This function is rarely used.

Filter callbacks are called in the order they are registered. If a filter
callback returns false then the message will not be dispatched
further, whether to other filters, or to channels, etc.

The message is the string or array with the raw message including,
the framing. The channelid is the channel identifier or an empty string
for control messages. If control is set then this is a control message,d
and the control argument contains the parsed JSON object of the
control message.

cockpit.transport.inject()

cockpit.transport.inject(message, [out])

Inject a message into the underlying channel transport. The message
should be a string or an array of bytes, and should be valid
according to the Cockpit message protocol. If the out argument is equal
to false then the message will be injected as an incoming message as if
it was received on the underlying channel transport.

This function is rarely used. In general you should only inject()
messages you got from a filter().

cockpit.base64_encode()

string = cockpit.base64_encode(data)

Encode binary data into a string using the Base64 encoding. The data
argument can either be a string, an Array, an ArrayBuffer
or a Uint8Array. The return value is a string.

cockpit.base64_decode()

data = cockpit.base64_decode(string, [constructor])

Decode binary data from a Base64 encoded string. The string
argument should be a javascript string. The returned data> will be an
array of bytes.

You can pass Uint8Array, Array or String
as an alternate constructor if you want the decoded data in an
alternate form. The default is to return an Array. Note that if you use a
String for the decoded data, then you must guarantee that the data
does not contain bytes that would be invalid for a string.

cockpit.utf8_encoder()

encoder = cockpit.utf8_encoder([constructor])

Create an encoder for encoding a string into a UTF8 sequence of bytes.

You can pass Uint8Array, Array or String
as an alternate constructor if you want the decoded data in an
alternate form. The default is to return an Array.

encoder.encode()

data = encoder.encode(string)

Encode a string into a UTF8 sequence of bytes.

The resulting data is an array of bytes, but it's type may be
modified by passing an alternate constructor to
cockpit.utf8_encoder().

cockpit.utf8_decoder()

decoder = cockpit.utf8_decoder([fatal])

Creates a decoder to decode a UTF8 sequence of bytes data into a string.

If the fatal is set to true then the decoder
will throw an exception when it encounters invalid UTF8 data. By default invalid data
will be substituted with special UTF8 characters.

decoder.decode()

string = decoder.decode(data, [options])

Decode an array of UTF8 bytes into a string. The data
argument may be an Array, a Uint8Array or a string containing
binary data.

If options is passed it should be a plain javascript object. If
options has a stream property equal to true,
then multiple invocations of this function can be made with parts of the UTF8 sequence
of bytes. Any trailing bytes that don't yet build a complete unicode character, will be
cached until the next invocation. To drain the last data, call this function without
the stream property set.