Help us shape the future of Go! Take the 2026 Go Developer Survey

bolt

package
v1.9.0 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package bolt is a server-side implementation of the Bolt protocol (v4.4 and v5.0 to v5.4) and PackStream.

Index

Constants

View Source
const (
	TagSuccess = msgSuccess
	TagRecord  = msgRecord
	TagIgnore  = msgIgnored
	TagFailure = msgFailure
)

Response tags a client can see.

View Source
const (
	TagHello    = msgHello
	TagGoodbye  = msgGoodbye
	TagReset    = msgReset
	TagRun      = msgRun
	TagBegin    = msgBegin
	TagCommit   = msgCommit
	TagRollback = msgRollback
	TagDiscard  = msgDiscard
	TagPull     = msgPull
	TagRoute    = msgRoute
	TagLogon    = msgLogon
	TagLogoff   = msgLogoff
)

Request tags a client can send.

View Source
const (
	CodeSyntax        = "Neo.ClientError.Statement.SyntaxError"
	CodeInvalid       = "Neo.ClientError.Request.Invalid"
	CodeUnauthorized  = "Neo.ClientError.Security.Unauthorized"
	CodeConstraint    = "Neo.ClientError.Schema.ConstraintValidationFailed"
	CodeTransient     = "Neo.TransientError.Transaction.Terminated"
	CodeDatabaseError = "Neo.DatabaseError.General.UnknownError"
	CodeProtocol      = "Neo.ClientError.Request.Invalid"
)

Failure codes sent to drivers.

View Source
const Preamble = 4

Preamble is the length of the Bolt magic preamble.

Variables

View Source
var (
	ErrTruncated   = errors.New("bolt: truncated packstream value")
	ErrTooDeep     = errors.New("bolt: packstream nesting too deep")
	ErrBadMarker   = errors.New("bolt: unknown packstream marker")
	ErrUnsupported = errors.New("bolt: unsupported value type")
	ErrTooLarge    = errors.New("bolt: packstream size exceeds message")
)

Errors returned while decoding.

View Source
var (
	ErrBadMagic   = errors.New("bolt: bad handshake preamble")
	ErrNoVersion  = errors.New("bolt: no common protocol version")
	ErrMsgTooBig  = errors.New("bolt: message exceeds size limit")
	ErrBadMessage = errors.New("bolt: malformed message")
)

Errors raised by the transport layer.

Functions

func Serve

func Serve(ctx context.Context, nc net.Conn, cfg Config)

Serve speaks Bolt on nc until the client leaves or ctx ends, then closes nc.

func Split

func Split(l net.Listener, serve func(net.Conn)) net.Listener

Split diverts connections that start with the Bolt preamble to serve and returns a listener that yields every other connection, so an HTTP server can share the port.

Types

type Backend

type Backend interface {
	NewSession() Session
	Authenticate(ctx context.Context, auth map[string]any) error
}

Backend creates sessions and checks credentials.

type Client

type Client struct {

	// Version is the negotiated protocol version.
	Version Version
	// contains filtered or unexported fields
}

Client is a minimal Bolt client for protocol tests.

func Dial

func Dial(rw io.ReadWriter, versions ...Version) (*Client, error)

Dial performs the handshake proposing the given versions (newest preference first, at most four).

func DialRaw

func DialRaw(rw io.ReadWriter, slots [16]byte) (*Client, error)

DialRaw sends the given 16 version bytes after the preamble.

func (*Client) Call

func (c *Client) Call(tag byte, fields ...any) (Response, error)

Call sends a request and reads one response.

func (*Client) PullAll

func (c *Client) PullAll(n int64) ([][]any, Response, error)

PullAll sends PULL and collects records until the terminating summary.

func (*Client) Query

func (c *Client) Query(query string, params map[string]any) ([][]any, Response, error)

Query runs an autocommit query and pulls every record, returning the rows and the final summary.

func (*Client) Recv

func (c *Client) Recv() (Response, error)

Recv reads one server message.

func (*Client) Send

func (c *Client) Send(tag byte, fields ...any) error

Send writes one request.

type Config

type Config struct {
	Backend Backend
	// Agent is the HELLO "server" string.
	Agent string
	// Database is reported as the default database name.
	Database string
	// Addr is the address advertised by ROUTE; the connection's local address is used when empty.
	Addr string
}

Config configures Serve.

type Decoder

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

Decoder reads PackStream values from a bounded in-memory message.

func NewDecoder

func NewDecoder(msg []byte) *Decoder

NewDecoder returns a decoder over msg.

func (*Decoder) Decode

func (d *Decoder) Decode() (any, error)

Decode reads one value.

func (*Decoder) Remaining

func (d *Decoder) Remaining() int

Remaining reports the undecoded byte count.

type Encoder

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

Encoder appends PackStream values to a buffer.

func NewEncoder

func NewEncoder(v Version) *Encoder

NewEncoder returns an encoder whose graph structures follow the given protocol version.

func (*Encoder) Bytes

func (e *Encoder) Bytes() []byte

Bytes returns the encoded bytes.

func (*Encoder) Encode

func (e *Encoder) Encode(v any) error

Encode appends v. Supported: nil, bool, ints, floats, string, []byte, []any, []string, map[string]any, *Struct, Node, Relationship, Path and the values wrapped by Neptune's adapter.

func (*Encoder) Reset

func (e *Encoder) Reset()

Reset clears the buffer.

type Error

type Error struct {
	Code    string
	Message string
}

Error is a failure reported to the client.

func (*Error) Error

func (e *Error) Error() string

type Node

type Node struct {
	Props     map[string]any
	ElementID string
	Labels    []string
	ID        int64
}

Node is a Bolt graph node. ElementID is sent from protocol 5.0.

type Path

type Path struct {
	Nodes   []Node
	Rels    []UnboundRelationship
	Indices []int64
}

Path is an alternating walk; Indices holds (rel index, node index) pairs, relationship indices 1-based and negative when traversed backwards.

type Relationship

type Relationship struct {
	Props          map[string]any
	ElementID      string
	Type           string
	StartElementID string
	EndElementID   string
	ID             int64
	StartID        int64
	EndID          int64
}

Relationship is a Bolt relationship with both endpoints.

type Response

type Response struct {
	Fields []any
	Tag    byte
}

Response is one server message.

func (Response) Meta

func (r Response) Meta() map[string]any

Meta returns the first field of a SUCCESS/FAILURE response as a map.

type Result

type Result struct {
	Fields []string
	Rows   [][]any
	Write  bool
}

Result is a fully materialised query result streamed to the client by PULL.

type Session

type Session interface {
	Run(ctx context.Context, query string, params map[string]any) (*Result, error)
	Begin(ctx context.Context) error
	Commit(ctx context.Context) error
	Rollback(ctx context.Context) error
	Close()
}

Session is one connection's view of the database. Run executes inside the open transaction, if any.

type Struct

type Struct struct {
	Fields []any
	Tag    byte
}

Struct is a generic PackStream structure (tag + fields).

type UnboundRelationship

type UnboundRelationship struct {
	Props     map[string]any
	ElementID string
	Type      string
	ID        int64
}

UnboundRelationship is a relationship inside a Path.

type Version

type Version struct {
	Major byte
	Minor byte
}

Version is a Bolt protocol version.

func Negotiate

func Negotiate(rw io.ReadWriter) (Version, error)

Negotiate reads the client's handshake and returns the chosen version, writing the 4-byte reply.

func Supported

func Supported() []Version

Supported lists the versions the server offers, newest first.

Jump to

Keyboard shortcuts

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