nativewire

package
v0.6.1 Latest Latest
Warning

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

 Go to latest Published: Jul 1, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package nativewire implements TreeDB's native client/server wire transport.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNilListener = fmt.Errorf("nativewire: nil listener: %w", net.ErrClosed)

ErrNilListener is returned when Serve is called with a nil listener. It wraps net.ErrClosed so callers that classify listener shutdown keep working.

View Source 
var ErrServerClosed = errors.New("nativewire: server is closed")

ErrServerClosed reports that the server is closed or refusing connections.

Functions

func AdmitClusterMutation 

func AdmitClusterMutation(ctx context.Context, submitter ClusterSubmitter) error

AdmitClusterMutation fails closed unless submitter is configured and, when it exposes admission state, the node is currently the leader.

func IsCatalogVersionMismatch 

func IsCatalogVersionMismatch(err error) bool

IsCatalogVersionMismatch reports whether err is a remote catalog-version guard failure.

func WithExpectedCatalogVersion 

func WithExpectedCatalogVersion(ctx context.Context, version uint64) context.Context

WithExpectedCatalogVersion attaches the catalog version guard to replicated mutations issued with ctx. When unset, the client reads or reuses the current version immediately before sending the mutation.

func WithIdempotencyKey 

func WithIdempotencyKey(ctx context.Context, key []byte) context.Context

WithIdempotencyKey attaches a caller-controlled idempotency key to replicated mutations issued with ctx. This lets callers retry the same logical mutation without the client generating a different key on each attempt.

Types

type AckPolicy 

type AckPolicy = iwire.AckPolicy
const (
	AckVisible       AckPolicy = iwire.AckVisible
	AckFlushed       AckPolicy = iwire.AckFlushed
	AckSynced        AckPolicy = iwire.AckSynced
	AckRaftCommitted AckPolicy = iwire.AckRaftCommitted
)

type AppliedIndexReadBarrierProvider 

type AppliedIndexReadBarrierProvider interface {
	LeaderReadBarrier(context.Context, ClusterReadRequest) (raftcluster.AppliedIndexReadBarrier, error)
}

AppliedIndexReadBarrierProvider supplies the applied-index target a leader_read must prove before nativewire serves local state.

type AppliedIndexReadCoordinator 

type AppliedIndexReadCoordinator struct {
	BarrierProvider   AppliedIndexReadBarrierProvider
	Waiter            raftcluster.AppliedIndexReadBarrierWaiter
	ReadIndexTarget   raftcluster.ReadIndexBarrier
	ReadIndexProvider raftcluster.ReadIndexProvider
}

AppliedIndexReadCoordinator bridges nativewire leader_read requests to the raftcluster applied-index read barrier foundation. Linearizable reads require a configured read-index provider with production evidence and then wait for local apply through the proven read index. Lease reads remain unsupported until a lease proof exists.

func (AppliedIndexReadCoordinator) CoordinateRead 

func (c AppliedIndexReadCoordinator) CoordinateRead(ctx context.Context, request ClusterReadRequest) (ClusterReadResult, error)

type CatalogClusterRouteProvider 

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

CatalogClusterRouteProvider adapts a validated raftplacement catalog to the nativewire route-preflight interface. It only returns catalog-derived metadata; it does not prove live leadership or submit routed commands.

func NewCatalogClusterRouteProvider 

func NewCatalogClusterRouteProvider(catalog raftplacement.ResolvedCatalogV1) CatalogClusterRouteProvider

NewCatalogClusterRouteProvider returns a route provider backed by a validated raftplacement catalog.

func (CatalogClusterRouteProvider) ClusterRoute 

func (p CatalogClusterRouteProvider) ClusterRoute(_ context.Context, request ClusterRouteRequest) (ClusterRouteTarget, error)

ClusterRoute resolves the request against the provider's catalog. Collection placements can satisfy collection, single-token, and token-batch requests with a collection target. Token/ring placements require a single token for submit targets; multi-token batches return classification metadata so preflight can fail closed before submit until split/fanout execution exists.

type Client 

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

Client serializes requests on one native-wire connection.

Byte slices returned by result APIs are immutable views into the client's response buffer. They remain valid until the next round trip on the same client; callers that need to keep them longer must copy them.

func DialContext 

func DialContext(ctx context.Context, network, address string) (*Client, error)

func NewClient 

func NewClient(conn net.Conn) *Client

NewClient returns a native-wire client that owns conn until Close.

func NewInProcessClient 

func NewInProcessClient(ctx context.Context, server *Server) (*Client, func() error, error)

func (*Client) Checkpoint 

func (c *Client) Checkpoint(ctx context.Context) error

func (*Client) CheckpointWithAck 

func (c *Client) CheckpointWithAck(ctx context.Context, ack AckPolicy) error

func (*Client) Close 

func (c *Client) Close() error

Close closes the underlying client connection.

func (*Client) CloseCollection 

func (c *Client) CloseCollection(ctx context.Context, handle CollectionHandle) error

func (*Client) CreateCollection 

func (c *Client) CreateCollection(ctx context.Context, meta collections.CollectionMeta) (collections.CollectionMeta, error)

func (*Client) CreateIndex 

func (c *Client) CreateIndex(ctx context.Context, collection string, def collections.IndexDefinition) (collections.CollectionMeta, error)

func (*Client) CurrentCatalogVersion 

func (c *Client) CurrentCatalogVersion(ctx context.Context) (uint64, error)

CurrentCatalogVersion returns the server-advertised catalog/schema version used by guarded replicated mutations.

func (*Client) CursorClose 

func (c *Client) CursorClose(ctx context.Context, cursorID uint64) error

func (*Client) CursorNext 

func (c *Client) CursorNext(ctx context.Context, cursorID uint64, limits CursorLimits) (DocumentsResult, error)

CursorNext fetches the next cursor batch. Returned ID and document slices borrow the client's response buffer and remain valid until the next round trip.

func (*Client) CursorNextWithOptions 

func (c *Client) CursorNextWithOptions(ctx context.Context, cursorID uint64, limits CursorLimits, opts ReadOptions) (DocumentsResult, error)

func (*Client) DeleteBatch 

func (c *Client) DeleteBatch(ctx context.Context, collection string, ids [][]byte, ack AckPolicy) (int, error)

func (*Client) DropIndex 

func (c *Client) DropIndex(ctx context.Context, collection, index string) (collections.CollectionMeta, error)

func (*Client) FlushAll 

func (c *Client) FlushAll(ctx context.Context) error

func (*Client) FlushAllWithAck 

func (c *Client) FlushAllWithAck(ctx context.Context, ack AckPolicy) error

func (*Client) FlushCollection 

func (c *Client) FlushCollection(ctx context.Context, collection string) error

func (*Client) FlushCollectionWithAck 

func (c *Client) FlushCollectionWithAck(ctx context.Context, collection string, ack AckPolicy) error

func (*Client) GetMany 

func (c *Client) GetMany(ctx context.Context, collection string, ids [][]byte) ([][]byte, []bool, error)

GetMany fetches documents by ID. Returned document slices borrow the client's response buffer and remain valid until the next round trip on this client.

func (*Client) GetManyHandle 

func (c *Client) GetManyHandle(ctx context.Context, handle CollectionHandle, ids [][]byte) ([][]byte, []bool, error)

GetManyHandle fetches documents by ID through an open collection handle. Returned document slices borrow the client's response buffer and remain valid until the next round trip on this client.

func (*Client) GetManyHandleWithOptions 

func (c *Client) GetManyHandleWithOptions(ctx context.Context, handle CollectionHandle, ids [][]byte, opts ReadOptions) (DocumentsResult, error)

func (*Client) GetManyWithOptions 

func (c *Client) GetManyWithOptions(ctx context.Context, collection string, ids [][]byte, opts ReadOptions) (DocumentsResult, error)

func (*Client) Goaway 

func (c *Client) Goaway(ctx context.Context) error

Goaway asks the server to close the connection gracefully.

func (*Client) Hello 

func (c *Client) Hello(ctx context.Context) error

Hello performs the native-wire hello handshake.

func (*Client) IndexLookup 

func (c *Client) IndexLookup(ctx context.Context, collection, index string, value any, limits CursorLimits) ([][]byte, bool, error)

IndexLookup returns IDs matching an index value. Returned ID slices borrow the client's response buffer and remain valid until the next round trip.

func (*Client) IndexLookupWithOptions 

func (c *Client) IndexLookupWithOptions(ctx context.Context, collection, index string, value any, limits CursorLimits, opts ReadOptions) (IDResult, error)

func (*Client) IndexRange 

func (c *Client) IndexRange(ctx context.Context, collection, index string, opts IndexRange) ([][]byte, bool, error)

IndexRange returns IDs within an index range. Returned ID slices borrow the client's response buffer and remain valid until the next round trip.

func (*Client) IndexRangeWithOptions 

func (c *Client) IndexRangeWithOptions(ctx context.Context, collection, index string, opts IndexRange, readOpts ReadOptions) (IDResult, error)

func (*Client) InsertBatch 

func (c *Client) InsertBatch(ctx context.Context, collection string, format collections.DocumentFormat, ids, docs [][]byte, ack AckPolicy) ([][]byte, error)

func (*Client) InsertBatchHandle 

func (c *Client) InsertBatchHandle(ctx context.Context, handle CollectionHandle, format collections.DocumentFormat, ids, docs [][]byte, ack AckPolicy) ([][]byte, error)

func (*Client) InsertBatchHandleNoResult 

func (c *Client) InsertBatchHandleNoResult(ctx context.Context, handle CollectionHandle, format collections.DocumentFormat, ids, docs [][]byte, ack AckPolicy) error

func (*Client) InsertBatchNoResult 

func (c *Client) InsertBatchNoResult(ctx context.Context, collection string, format collections.DocumentFormat, ids, docs [][]byte, ack AckPolicy) error

func (*Client) ListCollections 

func (c *Client) ListCollections(ctx context.Context) ([]collections.CollectionMeta, error)

func (*Client) ListIndexes 

func (c *Client) ListIndexes(ctx context.Context, collection string) ([]collections.IndexDefinition, error)

func (*Client) OpenCollection 

func (c *Client) OpenCollection(ctx context.Context, name string) (CollectionHandle, error)

func (*Client) OpenScan 

func (c *Client) OpenScan(ctx context.Context, collection string, limits CursorLimits) (DocumentsResult, error)

OpenScan starts a collection scan. Returned ID and document slices borrow the client's response buffer and remain valid until the next round trip.

func (*Client) OpenScanWithOptions 

func (c *Client) OpenScanWithOptions(ctx context.Context, collection string, limits CursorLimits, opts ReadOptions) (DocumentsResult, error)

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context) error

Ping sends a ping frame and waits for a pong response.

func (*Client) ReplaceBatch 

func (c *Client) ReplaceBatch(ctx context.Context, collection string, format collections.DocumentFormat, ids, docs [][]byte, ack AckPolicy) (matched, modified int, err error)

func (*Client) Stats 

func (c *Client) Stats(ctx context.Context) (map[string]string, error)

Stats fetches the server stats map over the native-wire stats command.

func (*Client) UpdateBSONSet 

func (c *Client) UpdateBSONSet(ctx context.Context, collection string, id []byte, fields []collections.BSONSetField, ack AckPolicy) (matched, modified int, err error)

func (*Client) UpdateBSONSetHandle 

func (c *Client) UpdateBSONSetHandle(ctx context.Context, handle CollectionHandle, id []byte, fields []collections.BSONSetField, ack AckPolicy) (matched, modified int, err error)

type ClusterAdmissionProvider 

type ClusterAdmissionProvider interface {
	ClusterAdmissionStatus(ctx context.Context) (ClusterAdmissionStatus, error)
}

ClusterAdmissionProvider exposes the node write-admission state backing a ClusterSubmitter. A configured cluster submitter that does not implement this interface fails closed as admission-unavailable.

type ClusterAdmissionStatus 

type ClusterAdmissionStatus struct {
	Leader      bool
	Unavailable bool
	LeaderHint  string
	Reason      string
}

ClusterAdmissionStatus describes whether this node may accept cluster-owned writes. A provider must set Leader for write admission; the zero value fails closed as not-leader when returned by a configured provider.

func ClusterFollowerAdmission 

func ClusterFollowerAdmission(leaderHint, reason string) ClusterAdmissionStatus

ClusterFollowerAdmission returns a fail-closed not-leader status. leaderHint is optional and may carry a redirect target for callers that can use one.

func ClusterLeaderAdmission 

func ClusterLeaderAdmission() ClusterAdmissionStatus

ClusterLeaderAdmission returns an admitted leader status.

func ClusterUnavailableAdmission 

func ClusterUnavailableAdmission(reason string) ClusterAdmissionStatus

ClusterUnavailableAdmission returns a fail-closed cluster-unavailable status.

type ClusterReadCoordinator 

type ClusterReadCoordinator interface {
	CoordinateRead(ctx context.Context, request ClusterReadRequest) (ClusterReadResult, error)
}

ClusterReadCoordinator proves cluster read barriers for native-wire reads. Implementations must fail closed: returning a strong ActualConsistency is the proof that the requested barrier was satisfied before the server reads local state.

type ClusterReadRequest 

type ClusterReadRequest struct {
	Policy      ConsistencyPolicy
	CommandID   iwire.CommandID
	CommandName string
	RequestID   uint64
	StreamID    uint64
}

type ClusterReadResult 

type ClusterReadResult struct {
	ActualConsistency ConsistencyPolicy
	ServingNode       string
	LeaderNode        string
	AppliedIndex      uint64
	HasAppliedIndex   bool
}

type ClusterRequestMetadata 

type ClusterRequestMetadata = raftentry.RequestMetadataV1

ClusterRequestMetadata carries request-scoped fields that influence response policy but are intentionally excluded from deterministic command entry bytes.

type ClusterRouteProvider 

type ClusterRouteProvider interface {
	ClusterRoute(ctx context.Context, request ClusterRouteRequest) (ClusterRouteTarget, error)
}

ClusterRouteProvider is an optional ClusterSubmitter extension for collection-level route preflight. Providers should use catalog-derived route decisions only; leader hints are metadata and are not live leadership proof.

type ClusterRouteRequest 

type ClusterRouteRequest struct {
	Database    string
	Catalog     string
	Collection  string
	CommandID   iwire.CommandID
	CommandName string
	Shape       ClusterRouteShape
	TokenKnown  bool
	Token       uint64
	Tokens      []uint64
}

type ClusterRouteShape 

type ClusterRouteShape string
const (
	ClusterRouteShapeCollection ClusterRouteShape = "collection"
	ClusterRouteShapeToken      ClusterRouteShape = "token"
	ClusterRouteShapeTokenBatch ClusterRouteShape = "token_batch"
)

type ClusterRouteTarget 

type ClusterRouteTarget struct {
	GroupID         string
	Members         []string
	LeaderHint      string
	PlacementMode   string
	Reason          string
	Shape           ClusterRouteShape
	TokenKnown      bool
	Token           uint64
	PartitionID     string
	TokenBatchClass string
}

func PreflightClusterRoute 

func PreflightClusterRoute(ctx context.Context, submitter ClusterSubmitter, request ClusterRouteRequest) (ClusterRouteTarget, bool, error)

PreflightClusterRoute checks the optional cluster route provider. A missing provider preserves existing submitter behavior; a configured provider must return a supported route target with a group ID. Token/ring targets require an exactly-one-ID token route request; multi-ID token batches are classified only so adapters can fail closed until split/fanout execution exists.

type ClusterSubmitResult 

type ClusterSubmitResult struct {
	ActualAck            AckPolicy
	CommittedRecoverable bool
	ResponseSections     []iwire.Section
	// CatalogVersion is internal post-apply evidence. It lets response shaping
	// omit response_meta without hiding catalog-cache progress from the server.
	CatalogVersion    uint64
	HasCatalogVersion bool
}

ClusterSubmitResult is the submitter-owned response for an admitted command. CommittedRecoverable must only be true when AckRaftCommitted reflects a real consensus commit plus the serving node's selected local recoverability gate.

type ClusterSubmitter 

type ClusterSubmitter interface {
	SubmitCommandEntryV1(ctx context.Context, entry []byte, metadata ClusterRequestMetadata) (ClusterSubmitResult, error)
}

ClusterSubmitter accepts deterministic native-wire CommandEntryV1 bytes for cluster-owned mutation admission. Submitters must copy entry bytes or response sections before retaining them after SubmitCommandEntryV1 returns.

type CollectionHandle 

type CollectionHandle uint64

type ConsistencyPolicy 

type ConsistencyPolicy = iwire.ConsistencyPolicy
const (
	ConsistencyLocalStale   ConsistencyPolicy = iwire.ConsistencyLocalStale
	ConsistencyLeaderRead   ConsistencyPolicy = iwire.ConsistencyLeaderRead
	ConsistencyLinearizable ConsistencyPolicy = iwire.ConsistencyLinearizable
	ConsistencyLeaseRead    ConsistencyPolicy = iwire.ConsistencyLeaseRead
)

type CursorLimits 

type CursorLimits struct {
	MaxItems int
	MaxBytes int
}

type CursorMeta 

type CursorMeta struct {
	CursorID uint64
	Items    int
	Bytes    int
	HasMore  bool
}

type DocumentsResult 

type DocumentsResult struct {
	IDs       [][]byte
	Docs      [][]byte
	Present   []bool
	Cursor    CursorMeta
	Truncated bool
	ReadMeta  ReadMetadata
}

DocumentsResult is a batched read result. ID and document slices returned by client APIs borrow the client's response buffer unless documented otherwise.

type IDResult 

type IDResult struct {
	IDs       [][]byte
	Truncated bool
	ReadMeta  ReadMetadata
}

type IndexRange 

type IndexRange struct {
	Lower          Scalar
	LowerInclusive bool
	LowerUnbounded bool
	Upper          Scalar
	UpperInclusive bool
	UpperUnbounded bool
	Limit          int
	MaxBytes       int
}

type RaftClusterSubmitter 

type RaftClusterSubmitter struct {
	Bridge      *raftcluster.SingleGroupSubmitter
	Collections *collections.CollectionManager
}

RaftClusterSubmitter adapts the internal single-group raftcluster bridge to the public nativewire ClusterSubmitter contract.

func NewRaftClusterSubmitter 

func NewRaftClusterSubmitter(bridge *raftcluster.SingleGroupSubmitter, managers ...*collections.CollectionManager) *RaftClusterSubmitter

func (*RaftClusterSubmitter) ClusterAdmissionStatus 

func (s *RaftClusterSubmitter) ClusterAdmissionStatus(ctx context.Context) (ClusterAdmissionStatus, error)

func (*RaftClusterSubmitter) SubmitCommandEntryV1 

func (s *RaftClusterSubmitter) SubmitCommandEntryV1(ctx context.Context, entry []byte, metadata ClusterRequestMetadata) (ClusterSubmitResult, error)

type ReadMetadata 

type ReadMetadata struct {
	Valid             bool
	ActualConsistency ConsistencyPolicy
	ServingNode       string
	LeaderNode        string
	AppliedIndex      uint64
	HasAppliedIndex   bool
}

ReadMetadata is returned from native read responses when the server can label the read contract it actually served.

type ReadOptions 

type ReadOptions struct {
	ConsistencyPolicy ConsistencyPolicy
}

ReadOptions carries native read policy controls. The zero value preserves the protocol default: serve locally and label the result local-stale.

type RoutedRaftClusterSubmitter 

type RoutedRaftClusterSubmitter struct {
	*RaftClusterSubmitter
	RouteProvider ClusterRouteProvider
}

RoutedRaftClusterSubmitter composes the concrete single-group Raft bridge with a catalog-backed route provider. The base RaftClusterSubmitter does not implement ClusterRouteProvider so existing no-provider behavior stays unchanged.

func NewRoutedRaftClusterSubmitter 

func NewRoutedRaftClusterSubmitter(bridge *raftcluster.SingleGroupSubmitter, provider ClusterRouteProvider, managers ...*collections.CollectionManager) *RoutedRaftClusterSubmitter

func (*RoutedRaftClusterSubmitter) ClusterRoute 

func (s *RoutedRaftClusterSubmitter) ClusterRoute(ctx context.Context, request ClusterRouteRequest) (ClusterRouteTarget, error)

type Scalar 

type Scalar struct {
	Type  collections.IndexValueType
	Value any
}

type Server 

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

Server serves native-wire control and command frames for TreeDB.

func NewServer 

func NewServer(opts ServerOptions) *Server

NewServer creates a native-wire server with defaulted limits and policies.

func (*Server) Close 

func (s *Server) Close() error

Close closes all active server connections and rejects new ones.

func (*Server) Serve 

func (s *Server) Serve(ctx context.Context, ln net.Listener) error

func (*Server) ServeConn 

func (s *Server) ServeConn(ctx context.Context, conn net.Conn) error

ServeConn serves native-wire frames on conn until shutdown, goaway, or error.

func (*Server) Stats 

func (s *Server) Stats() map[string]string

Stats returns the server's native-wire counters and backend stats.

type ServerOptions 

type ServerOptions struct {
	Limits                        iwire.Limits
	MaxInFlight                   int
	MaxConnections                int
	MaxCollectionHandles          int
	MaxCachedCollections          int
	MaxOpenCursors                int
	MaxCursorRetainedBytes        int
	MaxScanDocuments              int
	DefaultCursorBatchSize        int
	CursorIdleTimeout             time.Duration
	DefaultAckPolicy              iwire.AckPolicy
	MaxMetadataIdempotencyEntries int
	InsertBatchCombineMaxBatch    int
	InsertBatchCombineDrainYields int
	Collections                   *collections.CollectionManager
	Backend                       *backenddb.DB
	ClusterSubmitter              ClusterSubmitter
	ClusterReadCoordinator        ClusterReadCoordinator
}

ServerOptions configures a native-wire server.

type Stats 

type Stats map[string]string

Stats is a string-valued snapshot of native-wire and TreeDB counters.

type WireError 

type WireError struct {
	Code      iwire.ErrorCode
	Retryable bool
	Message   string
}

WireError is an error response decoded from a remote native-wire peer.

func (*WireError) Error 

func (e *WireError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.