trix

func DecodeHeader ¶ added in v0.2.0

func DecodeHeader(r io.Reader, magicNumber string) (map[string]interface{}, io.Reader, error)

DecodeHeader reads and validates a container's framing from r and returns the decoded header plus a reader positioned at the first payload byte.

Exactly PrefixSize+len(header) bytes are consumed — nothing is read ahead and nothing is buffered — so the returned reader (which is r itself) can be streamed, spliced or handed to an mmap-backed consumer without the payload ever being materialised.

header, payload, err := trix.DecodeHeader(f, "KVST")
if err != nil { return err }
_, err = io.Copy(dst, payload)

A checksum recorded in the header is NOT verified: verification needs the whole payload, which is precisely what this path refuses to hold. Callers that want it should hash the payload stream as they consume it.

package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/Snider/Enchantrix/pkg/trix"
)

func main() {
	var container bytes.Buffer
	if _, err := trix.EncodeStream(map[string]interface{}{"kind": "state-kv"}, "KVST", bytes.NewReader([]byte("binary tail")), &container); err != nil {
		log.Fatalf("EncodeStream failed: %v", err)
	}

	header, payload, err := trix.DecodeHeader(bytes.NewReader(container.Bytes()), "KVST")
	if err != nil {
		log.Fatalf("DecodeHeader failed: %v", err)
	}
	// payload is positioned at the first payload byte — stream it anywhere.
	var out bytes.Buffer
	if _, err := out.ReadFrom(payload); err != nil {
		log.Fatalf("copy failed: %v", err)
	}
	fmt.Printf("Header kind: %v\n", header["kind"])
	fmt.Printf("Payload: %s\n", out.String())
}

Output:
Header kind: state-kv
Payload: binary tail

func DecodeStream ¶ added in v0.2.0

func DecodeStream(r io.Reader, magicNumber string, payload io.Writer) (map[string]interface{}, int64, error)

DecodeStream reads a container from r and copies its payload to payload. It returns the decoded header and the number of payload bytes copied.

The payload is written out byte-for-byte as stored; see DecodeHeader for the checksum caveat.

header, n, err := trix.DecodeStream(f, "KVST", out)

func Encode ¶

func Encode(trix *Trix, magicNumber string, w io.Writer) ([]byte, error)

Encode serializes a Trix struct into the .trix binary format. It returns the encoded data as a byte slice.

package main

import (
	"fmt"
	"log"

	"github.com/Snider/Enchantrix/pkg/trix"
)

func main() {
	t := &trix.Trix{
		Header:  map[string]interface{}{"author": "Jules"},
		Payload: []byte("Hello, Trix!"),
	}
	encoded, err := trix.Encode(t, "TRIX", nil)
	if err != nil {
		log.Fatalf("Encode failed: %v", err)
	}
	fmt.Printf("Encoded data is not empty: %v\n", len(encoded) > 0)
}

Output:
Encoded data is not empty: true

func EncodeStream ¶ added in v0.2.0

func EncodeStream(header map[string]interface{}, magicNumber string, payload io.Reader, w io.Writer) (int64, error)

EncodeStream writes an RFC-0002 container to w, copying payload straight through rather than buffering it. It returns the total number of bytes written to w — the full container length, which matches len(Encode(...)) for the same header, magic and payload.

The wire format is byte-for-byte identical to Encode: the two differ only in how the payload reaches the writer. Encode needs the whole payload resident as a []byte; EncodeStream needs a copy buffer, so a 128k-token State log costs the same allocation as a one-byte one.

No transformation is applied to the payload — no sigil, no compression, no checksum, no encryption. The binary tail is exactly the bytes read from payload, so it can later become a zero-copy mmap of the source file. Callers wanting any of those apply them to the reader themselves.

f, _ := os.Create("session.kv")
src, _ := os.Open("session.mvlog")
n, err := trix.EncodeStream(map[string]interface{}{"kind": "state-kv"}, "KVST", src, f)

A nil payload is treated as an empty payload, matching Encode's handling of a nil Trix.Payload.

package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/Snider/Enchantrix/pkg/trix"
)

func main() {
	// The payload is copied straight from reader to writer, so a container
	// holding a multi-gigabyte log costs the same memory as a tiny one.
	payload := bytes.NewReader([]byte("a very long state log"))

	var out bytes.Buffer
	n, err := trix.EncodeStream(map[string]interface{}{"kind": "state-kv"}, "KVST", payload, &out)
	if err != nil {
		log.Fatalf("EncodeStream failed: %v", err)
	}
	fmt.Printf("Container length: %d\n", n)
}

Output:
Container length: 49