tnproto

Documentation

Overview

Package tnproto defines the types and functions necessary to speak the tenant control protocol.

Index

• Constants
• func Attach(dst net.Conn, id ID, key Key) error
• func Ping(dst net.Conn) error
• func ProxyExec(ctl *net.UnixConn, conn net.Conn) error
• func ReadHeader(src net.Conn) (ID, Key, error)
• type Buffer
  • func (b *Buffer) DirectExec(ctl *net.UnixConn, conn net.Conn) (io.ReadCloser, error)
  • func (b *Buffer) Prepare(t *plan.Tree, f OutputFormat) error
  • func (b *Buffer) Reset()
• type ID
  • func (id ID) IsZero() bool
  • func (id ID) String() string
• type Key
  • func (k Key) IsZero() bool
  • func (k Key) String() string
• type OutputFormat
  • func (o OutputFormat) String() string
• type Remote
  • func (r *Remote) Encode(dst *ion.Buffer, st *ion.Symtab)
  • func (r *Remote) Exec(ep *plan.ExecParams) error
  • func (r *Remote) SetField(f ion.Field) error
• type RemoteError
  • func (r *RemoteError) Error() string
• type Server
  • func (s *Server) Serve(ctl *net.UnixConn) error

Constants

const (
	// OutputRaw outputs a raw ion data stream
	OutputRaw = '0' + iota
	// OutputChunkedIon outputs an ion data stream
	// using HTTP chunked encoding
	OutputChunkedIon
	// OutputChunkedJSON outputs a JSON data stream
	// using HTTP chunked encoding
	OutputChunkedJSON
	// OutputChunkedJSONArray outputs a single
	// JSON array object using HTTP chunked encoding
	OutputChunkedJSONArray
)

const (
	HeaderSize = 96
	IDSize     = 24
	KeySize    = 32

	// MaxPayloadSize is the maximum
	// size of a tenant protocol message payload
	// (either a serialized AST expression or
	// a serialized subplan)
	MaxPayloadSize = (1 << 24) - 1
)

Functions

func Attach

func Attach(dst net.Conn, id ID, key Key) error

Attach takes a fresh connection to a remote tenant proxy and asks the remote proxy to attach this connection to the tenant given by id.

func Ping

func Ping(dst net.Conn) error

Ping sends an Attach message with a zero tenant ID and waits for the remote end to close the connection.

func ProxyExec

func ProxyExec(ctl *net.UnixConn, conn net.Conn) error

ProxyExec tells the tenant listening on the query socket to establish a connection over 'conn' for executing remote queries.

ProxyExec performs exactly one Write call on ctl, so it is safe to call ProxyExec on the same control socket from multiple goroutines sumultaneously.

The socket backing 'conn' will be served by the tenant using plan.Serve. See also: plan.Serve, plan.Client.

func ReadHeader

func ReadHeader(src net.Conn) (ID, Key, error)

ReadHeader reads an Attach message from the provided connection and returns the requested ID, or an error if the message could not be read.

See also: Attach

Types

type Buffer

type Buffer struct {
	// contains filtered or unexported fields
}

Buffer maintains temporary state for sending DirectExec messages. The zero value of Buffer is usable directly. Re-using a Buffer for DirectExec calls is encouraged, as it will reduce resource utilization.

func (*Buffer) DirectExec

func (b *Buffer) DirectExec(ctl *net.UnixConn, conn net.Conn) (io.ReadCloser, error)

DirectExec sends a query plan to a tenant over the control socket ctl and requests that it write query results into the socket represented by conn. DirectExec should only be called after Buffer.Prepare has been called at least once with the query that should be executed.

If the query is launched successfully, DirectExec returns an io.ReadCloser that can be used to read errors from the query execution. If the ReadCloser yields no output before EOF, then the query terminated successfully. Otherwise, the data returned via the ReadCloser will consist of error text describing how the query failed to execute. Closing the returned ReadCloser before reading the response implicitly cancels the query execution.

DirectExec makes multiple calls to read and write data via 'ctl', so the caller is required to synchronize access to the control socket in a reasonable manner to ensure that message exchanges are not interleaved.

func (*Buffer) Prepare

func (b *Buffer) Prepare(t *plan.Tree, f OutputFormat) error

Prepare resets the buffer and then prepepares a serialized query in [b]. Each call to Prepare overwrites the serialized query produced by preceding calls to Prepare.

func (*Buffer) Reset

func (b *Buffer) Reset()

Reset resets a Buffer to a state equivalent to the zero value of [b].

type ID

type ID [IDSize]byte

ID is the (opaque) tenant identifier. ID is used to isolate query execution environments.

func (ID) IsZero

func (id ID) IsZero() bool

func (ID) String

func (id ID) String() string

type Key

type Key [KeySize]byte

Key is the opaque tenant key. Key is used to authorize tenant requests.

func (Key) IsZero

func (k Key) IsZero() bool

func (Key) String

func (k Key) String() string

type OutputFormat

type OutputFormat byte

OutputFormat selects an output format for DirectExec requests.

The actual OutputFormat byte values are the ASCII digits starting at '0'

func (OutputFormat) String

func (o OutputFormat) String() string

type Remote

type Remote struct {
	// ID is the ID of the tenant
	// that we should connect to.
	ID ID

	// Key is the preshared key to authorize
	// requests to the tenant.
	Key Key

	// Net and Addr are the network
	// type and address of the remote
	// connection to make.
	// These arguments are passed
	// verbatim to net.Dial.
	Net, Addr string

	// Timeout, if non-zero, is the
	// dial timeout dialing the
	// remote connection.
	// This argument is passed verbatim
	// to net.DialTimeout; see the caveats
	// in net.DialTimeout for which steps
	// of dialing (like DNS resolution)
	// are part of the timeout window.
	Timeout time.Duration
}

Remote is an implementation of plan.Transport that asks a remote tenant to execute a query using a ProxyExec request.

func (*Remote) Encode

func (r *Remote) Encode(dst *ion.Buffer, st *ion.Symtab)

func (*Remote) Exec

func (r *Remote) Exec(ep *plan.ExecParams) error

Exec implements plan.Transport.Exec by dialing the address given by r.Net and r.Addr and sending it an Attach message, followed by a single query execution request with plan.Client.Exec.

See also: Attach

func (*Remote) SetField

func (r *Remote) SetField(f ion.Field) error

type RemoteError

type RemoteError struct {
	Text string
}

RemoteError is the type of error returned from operations where the remote machine decided to write an error response back to the client.

func (*RemoteError) Error

func (r *RemoteError) Error() string

Error implements error

type Server

type Server struct {
	plan.Server
	Logf func(f string, args ...any)
}

func (*Server) Serve

func (s *Server) Serve(ctl *net.UnixConn) error

Serve responds to ProxyExec and DirectExec requests over the given control socket.