channel

package
v0.0.61 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 21, 2019 License: BSD-3-Clause Imports: 8 Imported by: 0

Documentation

Overview

Package channel defines a communications channel that can encode/transmit and decode/receive data records with a configurable framing discipline, and provides some simple framing implementations.

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

View Source
var JSON = Header("application/json")

JSON is a header framing (see Header) with MIME type application/json.

View Source
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

View Source
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.

View Source
var NUL = Split('\x00')

NUL is a framing discipline for messages terminated by a Unicode NUL (0). This framing has the constraint that records may not contain NUL.

Functions

func IsErrClosing added in v0.0.23

func IsErrClosing(err error) bool

IsErrClosing reports whether err is the internal error returned by a read from a pipe or socket that is closed. This is false for err == nil.

Types

type Channel

type Channel interface {
	Sender
	Receiver

	// Close shuts down the channel, after which no further records may be
	// sent or received.
	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 higher-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.

func Decimal added in v0.0.26

func Decimal(r io.Reader, wc io.WriteCloser) Channel

Decimal is a framing that transmits and receives messages on r and wc, with each message prefixed by its length encoded as a line of decimal digits.

For example, the message "empanada\n" is encoded as:

9\n
empanada\n

func Direct added in v0.0.61

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.

func RawJSON added in v0.0.8

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.

func Varint

func Varint(r io.Reader, wc io.WriteCloser) Channel

Varint is a framing that transmits and receives messages on r and wc, with each message prefixed by its length encoded in a varint as defined by the encoding/binary package.

func WithTrigger added in v0.0.16

func WithTrigger(ch Channel, trigger func()) Channel

WithTrigger returns a Channel that delegates I/O operations to ch, and when a Recv operation on ch returns io.EOF it synchronously calls the trigger.

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(mimeType string) Framing

Header 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. Note, however, that the framing function returned by Header does not verify that the encoding of messages matches the declared mimeType.

func Split added in v0.0.20

func Split(b byte) Framing

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.

type Receiver added in v0.0.6

type Receiver interface {
	// 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)
}

A Receiver represents the ability to receive a message from a channel.

type Sender added in v0.0.6

type Sender interface {
	// Send transmits a record on the channel. Each call to Send transmits one
	// complete record.
	Send([]byte) error
}

A Sender represents the ability to transmit a message on a channel.

Directories

Path Synopsis
Package chanutil exports helper functions for working with channels and framing defined by the bitbucket.org/creachadair/jrpc2/channel package.
Package chanutil exports helper functions for working with channels and framing defined by the bitbucket.org/creachadair/jrpc2/channel package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL