Documentation
¶
Overview ¶
Package cursor provides version and ordering abstractions for tracking event positions.
Cursor implements the synckit/types.Version interface to support multiple versioning strategies: simple integer sequence numbers, vector clocks, and pluggable custom implementations. Cursors enable efficient event pagination, conflict detection, and causality tracking in distributed systems.
Wire Format ¶
Cursors can be marshaled to a JSON wire format (WireCursor) for transport over HTTP or other protocols. Use MarshalWire and UnmarshalWire for serialization.
Pluggable Codecs ¶
Custom cursor implementations can be registered via Register so they are available for wire round-trips. The built-in implementations are IntegerCursor and VectorCursor.
See also:
- README: https://github.com/c0deZ3R0/go-sync-kit#readme
- Architecture overview: https://github.com/c0deZ3R0/go-sync-kit/blob/main/docs/overview.md
Index ¶
Constants ¶
const ( // KindInteger is the kind identifier for IntegerCursor. KindInteger = "integer" // KindVector is the kind identifier for VectorCursor. KindVector = "vector" )
Variables ¶
This section is empty.
Functions ¶
func EncodeUvarint ¶
Optional: compact binary helpers if you later want non-JSON wire payloads.
func InitDefaultCodecs ¶
func InitDefaultCodecs()
func Register ¶
func Register(c Codec)
Register registers a Codec implementation in the global registry.
func ValidateWireCursor ¶
func ValidateWireCursor(wc *WireCursor) error
ValidateWireCursor checks that a WireCursor is valid before unmarshaling.
Types ¶
type Codec ¶
type Codec interface {
// Kind returns the cursor kind this codec handles.
Kind() string
// Marshal encodes a Cursor to JSON wire format.
Marshal(c Cursor) (json.RawMessage, error)
// Unmarshal decodes JSON wire format back to a Cursor.
Unmarshal(data json.RawMessage) (Cursor, error)
}
Codec defines the interface for marshaling and unmarshaling cursors to wire format.
type ConcurrentTestCodec ¶
type ConcurrentTestCodec struct {
ID string
}
ConcurrentTestCodec is a test-only codec for concurrent registry tests
func (ConcurrentTestCodec) Kind ¶
func (c ConcurrentTestCodec) Kind() string
func (ConcurrentTestCodec) Marshal ¶
func (ConcurrentTestCodec) Marshal(c Cursor) (json.RawMessage, error)
func (ConcurrentTestCodec) Unmarshal ¶
func (ConcurrentTestCodec) Unmarshal(data json.RawMessage) (Cursor, error)
type Cursor ¶
type Cursor interface {
// Kind returns the kind string identifying the cursor type.
Kind() string
}
Cursor is the interface for version/ordering abstractions.
func MustUnmarshalWire ¶ added in v0.10.0
MustUnmarshalWire unmarshals a WireCursor to a Cursor, panicking on error This is useful for cases where the wire cursor is known to be valid
func UnmarshalWire ¶
func UnmarshalWire(wc *WireCursor) (Cursor, error)
UnmarshalWire decodes a WireCursor back to a Cursor.
type IntegerCursor ¶
type IntegerCursor struct {
// Seq is the sequence number.
Seq uint64
}
IntegerCursor is a simple high-water mark (sequence number) version.
func NewInteger ¶ added in v0.10.0
func NewInteger(seq uint64) IntegerCursor
NewInteger creates a new IntegerCursor with the given sequence number
func (IntegerCursor) Compare ¶
func (ic IntegerCursor) Compare(other types.Version) int
Compare implements types.Version
func (IntegerCursor) Kind ¶
func (IntegerCursor) Kind() string
Kind returns the cursor kind identifier.
func (IntegerCursor) String ¶
func (ic IntegerCursor) String() string
String implements types.Version
type VectorCursor ¶
type VectorCursor struct {
// Counters maps node identifiers to their logical clock values.
Counters map[string]uint64
}
VectorCursor is a vector clock version: map[node]counter.
func NewVector ¶ added in v0.10.0
func NewVector(counters map[string]uint64) VectorCursor
NewVector creates a new VectorCursor with the given counters
func (VectorCursor) Compare ¶
func (vc VectorCursor) Compare(other types.Version) int
Compare implements types.Version
func (VectorCursor) Kind ¶
func (VectorCursor) Kind() string
Kind returns the cursor kind identifier.
type WireCursor ¶
type WireCursor struct {
// Kind identifies the cursor type.
Kind string `json:"kind"`
// Data holds the codec-specific JSON encoding.
Data json.RawMessage `json:"data"`
}
WireCursor is the JSON-serializable representation of a Cursor for transport.
func MarshalWire ¶
func MarshalWire(c Cursor) (*WireCursor, error)
MarshalWire encodes a Cursor to WireCursor format for transport.
func MustMarshalWire ¶ added in v0.10.0
func MustMarshalWire(c Cursor) WireCursor
MustMarshalWire marshals a cursor to WireCursor format, panicking on error This is useful for cases where the cursor is known to be valid
Source Files