Documentation
¶
Overview ¶
Package channel defines a communications channel.
A Channel encodes/transmits and decodes/receives data records. The types in this package support sending and receiving over an unstructured stream using a configurable framing discipline.
Channels ¶
A Channel represents the ability to send and received framed records, comprising the methods:
Send([]byte) error // send a single complete record Recv() ([]byte, error) // receive a single complete record Close() error // close the channel
Each record passed to Send is available for Recv. Record contents are not interpreted (except as noted below), and it is up to the implementation to decide how records are framed for transport. A channel must support use by one sender and one receiver concurrently, but is not otherwise required to be safe for concurrent use.
Framing ¶
A Framing function adapts a pair of io.Reader and io.WriteCloser to a Channel by imposing a particular message-framing discipline. This package provides several framing implementations, for example:
ch := channel.LSP(r, wc)
creates a channel that reads from r and writes to wc using the Language Server Protocol (LSP) framing defined by https://microsoft.github.io/language-server-protocol/specification.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.New("channel is closed")
ErrClosed is a sentinel error that can be returned to indicate an operation failed because the channel was closed.
var LSP = Header("application/vscode-jsonrpc; charset=utf-8")
LSP is a header framing (see Header) that transmits and receives messages on r and wc using the MIME type application/vscode-jsonrpc. This is the format preferred by the Language Server Protocol (LSP), defined by https://microsoft.github.io/language-server-protocol
var Line = Split('\n')
Line is a framing discipline for messages terminated by a Unicode LF (10). This framing has the constraint that records may not contain LF.
Functions ¶
func IsErrClosing ¶
IsErrClosing reports whether err is a channel-closed error. This is true for the internal error returned by a read from a pipe or socket that is closed, or an error that wraps ErrClosed. It is false if err == nil.
Types ¶
type Channel ¶
type Channel interface {
// Send transmits a record on the channel. Each call to Send transmits one
// complete record.
Send([]byte) error
// Recv returns the next available record from the channel. If no further
// messages are available, it returns nil, io.EOF. Each call to Recv
// fetches a single complete record.
Recv() ([]byte, error)
// Close shuts down the channel, after which no further records may be sent.
Close() error
}
A Channel represents the ability to transmit and receive data records. A channel does not interpret the contents of a record, but may add and remove framing so that records can be embedded in lower-level protocols.
One sender and one receiver may use a Channel concurrently, but the methods of a Channel are not otherwise required to be safe for concurrent use. The order of records received must be the same as the order sent.
func Direct ¶
func Direct() (client, server Channel)
Direct returns a pair of synchronous connected channels that pass message buffers directly in memory without framing or encoding. Sends to client will be received by server, and vice versa.
Note that buffers passed to direct channels are not copied. If the caller needs to use the buffer after sending it on a direct channel, the caller is responsible for making a copy.
func RawJSON ¶
func RawJSON(r io.Reader, wc io.WriteCloser) Channel
RawJSON is a framing that transmits and receives records on r and wc, in which each record is defined by being a complete JSON value. No padding or other separation is added.
A RawJSON channel has no out-of-band framing, so the channel cannot usually recover after a message that is not syntactically valid JSON. Applications that need a channel to survive invalid JSON should avoid this framing.
type ContentTypeMismatchError ¶ added in v0.6.1
type ContentTypeMismatchError struct {
Got, Want string // the observed and expected content type values
}
A ContentTypeMismatchError is reported by the Recv method of a Header framing when the content type of the message does not match the type expected by the channel.
func (*ContentTypeMismatchError) Error ¶ added in v0.6.1
func (c *ContentTypeMismatchError) Error() string
type Framing ¶
type Framing func(io.Reader, io.WriteCloser) Channel
A Framing converts a reader and a writer into a Channel with a particular message-framing discipline.
func Header ¶
Header returns a framing that behaves as StrictHeader, but allows received messages to omit the Content-Type header without error. An error will still be reported if a content-type is set but does not match.
func Split ¶
Split returns a framing in which each message is terminated by the specified byte value. The framing has the constraint that outbound records may not contain the split byte internally.
func StrictHeader ¶ added in v0.6.1
StrictHeader defines a Framing that transmits and receives messages using a header prefix similar to HTTP, in which mimeType describes the content type.
Specifically, each message is sent in the format:
Content-Type: <mime-type>\r\n Content-Length: <nbytes>\r\n \r\n <payload>
The length (nbytes) is encoded as decimal digits. For example, given a mimeType value "application/json", the message "123\n" is transmitted as:
Content-Type: application/json\r\n Content-Length: 4\r\n \r\n 123\n
If mimeType == "", the Content-Type header is omitted when sending.
If the content type of an otherwise-valid received message does not match the expected value, Recv returns the decoded message along with an error of concrete type *ContentTypeMismatchError.
Note: The framing returned by StrictHeader does not verify the encoding of a message matches the declared mimeType.
Source Files