koutendb

README

KoutenDB Go Driver

Native Go TCP access and an optional embedded C ABI wrapper for KoutenDB.

Mode	Import	Native dependencies
TCP server	github.com/puffball1567/koutendb-go	None; works with CGO_ENABLED=0
Embedded	github.com/puffball1567/koutendb-go/embedded	C compiler and ABI v2 libkoutendb; kouten_embedded build tag

Go 1.26 or newer. Both transports preserve raw, JSON, NIF and BIF payloads; NIF/BIF encoding and decoding remain application responsibilities.

Native TCP

Add the module to your application:

go get github.com/puffball1567/koutendb-go@v0.1.0

Source, examples and tagged releases are available in this repository. API documentation is available on pkg.go.dev.

Start a local server using the KoutenDB distribution:

koutend --id=0 --peers=127.0.0.1:17301 --data=./data

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    kouten "github.com/puffball1567/koutendb-go"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    db, err := kouten.Dial(ctx, []string{"127.0.0.1:17301"}, kouten.Options{})
    if err != nil { log.Fatal(err) }
    defer db.Close()

    id, err := db.PutJSON(ctx, "articles", map[string]string{"title": "Hello"})
    if err != nil { log.Fatal(err) }
    var article struct { Title string }
    found, err := db.GetJSON(ctx, id, &article)
    if err != nil { log.Fatal(err) }
    fmt.Println(found, article.Title, id.String())
}

Clients serialize requests and can be shared between goroutines. Use multiple clients for parallel requests. Every operation accepts a context; cancellation also interrupts in-flight socket I/O and waiting for the client lock.

See TCP setup, authentication, TLS and errors.

Embedded

Build the shared library from a compatible KoutenDB checkout:

cd ../koutendb
bash scripts/build_capi.sh

From this driver checkout on Linux:

export CGO_LDFLAGS="-L$(realpath ../koutendb/lib)"
export LD_LIBRARY_PATH="$(realpath ../koutendb/lib)${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
go run -tags=kouten_embedded ./examples/embedded

On macOS, build with KOUTENDB_CAPI_OUT=lib/libkoutendb.dylib bash scripts/build_capi.sh and set DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH. If the library is installed in the system loader's search path, these path settings are not needed. The C header is included in this package.

Embedded supports in-memory and persistent stores, codec-aware CRUD, vector insertion, JSON selection and ring-page reads. Each handle owns a dedicated OS thread so C ABI calls and thread-local error capture remain together. Always call Close; no garbage-collection finalizer owns the database lifecycle.

See embedded API and examples.

Compatibility and Validation

Capability	Native TCP	Embedded
Put, JSON put, get, JSON get, query	Yes	Yes
Codec metadata, empty/binary payloads	Yes	Yes
Health, authentication, verified TLS	Yes	Not applicable
Update / remove	Not yet exposed	Yes
Ring filtering, selection, sorting, pagination	Not yet exposed	Yes
Vector insertion	Not yet exposed	Yes
Administrative APIs / full driver parity	Not yet exposed	Not yet exposed

The initial native transport targets wire v1; it fails closed on another wire version. Embedded requires C ABI v2 and the symbols used by this release. Its four-field ID is intentionally distinct from the six-field TCP ID.

Validation matrix and commands cover the shared protocol suite, real authenticated/TLS servers, partial I/O, invalid frames, cancellation, concurrent operations, persistence and race detection. Linux/macOS CI includes real-server and C ABI checks; Windows CI covers native Go tests.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package koutendb provides a native Go TCP client for KoutenDB wire v1. It does not require cgo or libkoutendb. Clients serialize operations and may be shared by goroutines. Use separate clients for parallel requests.

Index

• Variables
• type Client
  • func Dial(ctx context.Context, peers []string, options Options) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Get(ctx context.Context, id ID) (*Payload, error)
  • func (c *Client) GetJSON(ctx context.Context, id ID, dst any) (bool, error)
  • func (c *Client) GoString() string
  • func (c *Client) Health(ctx context.Context) (string, error)
  • func (c *Client) Put(ctx context.Context, ring string, data []byte) (ID, error)
  • func (c *Client) PutCodec(ctx context.Context, ring string, data []byte, codec Codec) (ID, error)
  • func (c *Client) PutJSON(ctx context.Context, ring string, value any) (ID, error)
  • func (c *Client) Query(ctx context.Context, id ID, selection string) (*Payload, error)
  • func (c *Client) QueryJSON(ctx context.Context, id ID, selection string, dst any) (bool, error)
  • func (c *Client) String() string
• type Codec
  • func (c Codec) Valid() bool
• type Credentials
  • func (c Credentials) GoString() string
  • func (Credentials) MarshalJSON() ([]byte, error)
  • func (Credentials) String() string
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Is(target error) bool
  • func (e *Error) Unwrap() error
• type ID
  • func ParseID(s string) (ID, error)
  • func (id ID) MarshalText() ([]byte, error)
  • func (id ID) String() string
  • func (id *ID) UnmarshalText(b []byte) error
• type Options
  • func (o Options) GoString() string
  • func (Options) MarshalJSON() ([]byte, error)
  • func (Options) String() string
• type Payload
• type TLSOptions

Variables

var (
	ErrConnection         = &Error{kind: "connection", message: "koutendb: connection failed"}
	ErrTimeout            = &Error{kind: "timeout", message: "koutendb: operation timed out"}
	ErrAuthentication     = &Error{kind: "authentication", message: "koutendb: authentication rejected"}
	ErrProtocol           = &Error{kind: "protocol", message: "koutendb: invalid wire response"}
	ErrVersionMismatch    = &Error{kind: "version", message: "koutendb: unsupported wire version"}
	ErrServer             = &Error{kind: "server", message: "koutendb: server rejected request"}
	ErrIndeterminateWrite = &Error{kind: "indeterminate", message: "koutendb: write outcome unknown; do not automatically retry"}
	ErrInvalidInput       = &Error{kind: "input", message: "koutendb: invalid option or request"}
	ErrClosed             = &Error{kind: "closed", message: "koutendb: client closed"}
)

Types

type Client

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

Client is concurrency-safe. Do not copy a Client after Dial.

func Dial

func Dial(ctx context.Context, peers []string, options Options) (*Client, error)

Dial connects, authenticates and checks wire compatibility before returning.

func (*Client) Close

func (c *Client) Close() error

Close waits for the current bounded operation, closes all peers, and is idempotent.

func (*Client) Get

func (c *Client) Get(ctx context.Context, id ID) (*Payload, error)

Get returns nil for MISS/GONE; an empty stored value has a non-nil Payload.

func (*Client) GetJSON

func (c *Client) GetJSON(ctx context.Context, id ID, dst any) (bool, error)

GetJSON decodes JSON into dst and returns whether the record exists.

func (*Client) GoString

func (c *Client) GoString() string

func (*Client) Health

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

func (*Client) Put

func (c *Client) Put(ctx context.Context, ring string, data []byte) (ID, error)

Put stores raw bytes. A write with an unknown outcome is never retried.

func (*Client) PutCodec

func (c *Client) PutCodec(ctx context.Context, ring string, data []byte, codec Codec) (ID, error)

func (*Client) PutJSON

func (c *Client) PutJSON(ctx context.Context, ring string, value any) (ID, error)

func (*Client) Query

func (c *Client) Query(ctx context.Context, id ID, selection string) (*Payload, error)

func (*Client) QueryJSON

func (c *Client) QueryJSON(ctx context.Context, id ID, selection string, dst any) (bool, error)

func (*Client) String

func (c *Client) String() string

type Codec

type Codec string

const (
	Raw  Codec = "raw"
	JSON Codec = "json"
	NIF  Codec = "nif"
	BIF  Codec = "bif"
)

func (Codec) Valid

func (c Codec) Valid() bool

type Credentials

type Credentials struct{ Username, Password, AuthToken, SecretKey string }

func (Credentials) GoString

func (c Credentials) GoString() string

func (Credentials) MarshalJSON

func (Credentials) MarshalJSON() ([]byte, error)

func (Credentials) String

func (Credentials) String() string

type Error

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

Error identifies a failure without exposing server messages or credentials.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Is

func (e *Error) Is(target error) bool

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ID

type ID struct {
	Parent uint64
	Epoch  uint32
	Seq    uint32
	TWrite float64
	Period float64
	Head   float64
}

ID preserves all six server-supplied fields. Never calculate placement locally.

func ParseID

func ParseID(s string) (ID, error)

ParseID parses the complete colon-separated wire identity.

func (ID) MarshalText

func (id ID) MarshalText() ([]byte, error)

func (ID) String

func (id ID) String() string

func (*ID) UnmarshalText

func (id *ID) UnmarshalText(b []byte) error

type Options

type Options struct {
	ConnectTimeout, ReadTimeout, WriteTimeout time.Duration
	MaxFrameBytes                             int
	MaxRedirects                              int
	DisableReadRetry                          bool
	Credentials                               Credentials
	Galaxy                                    string
	TLS                                       *TLSOptions
}

Options is copied at Dial. Zero durations/limits select defaults.

func (Options) GoString

func (o Options) GoString() string

func (Options) MarshalJSON

func (Options) MarshalJSON() ([]byte, error)

func (Options) String

func (Options) String() string

type Payload

type Payload struct {
	Data  []byte
	Codec Codec
}

Payload distinguishes an empty value from an absent record (a nil *Payload).

type TLSOptions

type TLSOptions struct {
	CAFile     string
	ServerName string
	// InsecureSkipVerify disables chain and hostname checks. Development only.
	InsecureSkipVerify bool
}