protocol

README

📦 Protocol Package – README

Location: internal/protocol/README.md Purpose: Document the design, API, and ultra‑low‑latency zero‑allocation parser used by the Tellstone in‑memory DB for translating simple SQL‑style statements into internal ParsedQuery structures.

🚀 Overview

The protocol package provides a hand‑rolled, allocation‑free parser for a tiny SQL‑dialect that maps directly to the key‑value engine. It supports three commands:

Command	Example
GET (SELECT)	SELECT value FROM kv WHERE key='myKey'
SET (INSERT)	INSERT INTO kv (key, value, ttl_ms) VALUES ('myKey','myVal',5000)
DELETE	DELETE FROM kv WHERE key='myKey'

Case‑insensitive, tolerant of extra whitespace, and works directly on the incoming []byte without allocating any heap memory. All slices returned by the parser point back into the original buffer.

⚡ Quick Start

package main

import (
    "fmt"
    "time"
    "github.com/Saxy/Tellstone/internal/protocol"
)

func main() {
    // Example INSERT with TTL of 5 seconds
    raw := []byte("INSERT INTO kv (key, value, ttl_ms) VALUES ('session:123','payload',5000)")
    q, err := protocol.ParseQuery(raw)
    if err != nil {
        fmt.Printf("parse error: %v\n", err)
        return
    }

    switch q.Type {
    case protocol.CmdSet:
        fmt.Printf("key=%s value=%s ttl=%s\n", q.Key, q.Value, q.TTL)
    }
}

The program runs with zero heap allocations on the hot path (the only allocations are the static error values).

🛠️ API Summary

package protocol

import "time"

// CommandType enumerates supported statements.
type CommandType uint8

const (
    CmdUnknown CommandType = iota
    CmdGet
    CmdSet
    CmdDelete
)

// ParsedQuery is the result of a successful parse.
type ParsedQuery struct {
    Type  CommandType   // CmdGet / CmdSet / CmdDelete
    Key   []byte        // raw key slice (no copy)
    Value []byte        // raw value slice (only for CmdSet)
    TTL   time.Duration // TTL in ms (zero for no TTL)
}

// Errors returned by ParseQuery.
var (
    ErrParse       = errors.New("invalid query")      // generic parse failure
    ErrTTLOverflow = errors.New("ttl overflow")       // TTL > 24 h (configurable)
)

// ParseQuery parses a raw SQL‑style query.
// It never allocates on the heap (except the static error values).
func ParseQuery(raw []byte) (ParsedQuery, error)

📈 🏎️ Benchmark Results

All benchmarks were executed with go test -bench=. ./internal/protocol on an AMD Ryzen 9 9950X (16‑core, 3.4 GHz).

Benchmark	ns/op	B/op	allocs/op
Select_Sequential	26 ns	0 B	0
Insert_Sequential	86 ns	0 B	0
Select_Whitespace_Sequential	31 ns	0 B	0
Select_MixedCase_Sequential	27 ns	0 B	0
Insert_LongValue_Sequential (~2 KB)	853 ns	0 B	0
Insert_TTLOverflow_Sequential	54 ns	0 B	0
Select_UTF8Key_Sequential	27 ns	0 B	0
Select_Parallel	11 ns	0 B	0
Insert_Parallel	12 ns	0 B	0
MixedParallel_Mix_Parallel (GET/SET/DELETE round‑robin)	12 ns	0 B	0

Interpretation

• Sub‑30 ns latency for normal queries, even with extra whitespace or mixed‑case keywords.
• Parallel execution halves the latency because the parser is completely thread‑safe and lock‑free.
• The longest benchmark (2 KB payload) still incurs 0 allocations, confirming the zero‑allocation guarantee.

📂 Package Contents

parser.go            – Core zero‑allocation parser implementation
parser_bench_test.go – Benchmark suite covering sequential, parallel, and edge‑case scenarios
parser_test.go       – Unit tests for valid/invalid queries and TTL overflow
protocol.go          – CommandType enum and ParsedQuery definition

🔨 Development & Testing

# Run unit tests (including TTL overflow case)
go test ./...

# Run the full benchmark suite with allocation reporting
go test -bench=. -benchmem ./internal/protocol

📌 Architectural Constraints & Boundaries

• No heap allocations on the hot path – all helpers operate on the original byte slice.
• ASCII‑only case folding – the parser lower‑cases bytes manually; non‑ASCII characters are passed through unchanged. If Unicode case‑folding is required, a separate slow‑path can be added.
• TTL limit – values greater than 24 hours are rejected with ErrTTLOverflow. Adjust the constant in extractSetPayloadInline if a different limit is needed.
• Error handling – callers must check the returned error before using the parsed fields.

🌱 Future Work

• SIMD‑accelerated case folding for even lower latency.
• Configurable maximum TTL via a package‑level variable.
• Support for batch IN queries and optional IF NOT EXISTS clauses.
• Auto‑generated BENCHMARKS.md from benchmark output.
• Integration tests exercising zero‑copy parsing from network sockets.

Documentation

Overview

Package protocol Tellstone Cloud-Native In-Memory Database File: parser.go Description: Statically inlined, zero-allocation byte-scanner for relational

SQL text-queries. Eliminates heap allocations and AST-overhead
by operating directly on live network transaction buffers.

"Speed is not about doing things faster, but about doing less things."

Authors:

Maximilian Hagen

Package protocol Tellstone Cloud-Native In-Memory Database Description: The Relational Translation Matrix. A high-performance,

zero-allocation text-query scanner that decouples database
wire frontends from the inner storage engine.

"Every protocol speaks a different language; bytes are the ultimate truth."

Authors:

Maximilian Hagen

Index

• Variables
• type CommandType
• type ParsedQuery
  • func ParseQuery(raw []byte, logger log.Logger) (ParsedQuery, error)

Variables

var ErrParse = errors.New("invalid query")

ErrParse is returned when the input SQL cannot be parsed into a valid query.

var ErrTTLOverflow = errors.New("ttl overflow")

ErrTTLOverflow signals that a TTL value is unreasonably large (overflow).

Types

type CommandType

type CommandType byte

CommandType represents a raw, byte-bound enumerator signaling the transactional intent extracted from an incoming database query. It maps relational SQL keywords directly onto internal key-value operations.

const (
	// CmdUnknown indicates an unparseable syntax, missing keywords, or a non-KV query.
	// In production, this triggers a fallback database error response to the client.
	CmdUnknown CommandType = iota

	// CmdGet signals a value retrieval intent (e.g., matching a relational SELECT).
	// This routes the execution path directly to Engine.Get().
	CmdGet

	// CmdSet signals an upsert intent (e.g., matching a relational INSERT or UPDATE).
	// This routes the execution path directly to Engine.Set().
	CmdSet

	// CmdDelete signals an explicit key evacuation intent (e.g., matching a relational DELETE).
	// This routes the execution path directly to Engine.Delete().
	CmdDelete
)

type ParsedQuery

type ParsedQuery struct {
	// Type dictates the tactical routing path inside the database engine loop.
	Type CommandType

	// Key is a direct zero-copy sub-slice pointing precisely to the key window
	// within the incoming TCP connection network read buffer.
	// All surrounding quotes or whitespaces are already stripped inline.
	//
	// LIFETIME WARNING: This slice points directly to transient network memory.
	// It must either be consumed immediately during a read operation or copied
	// by the storage map engine during a write operation.
	Key []byte

	// Value represents the raw, unparsed binary database payload. It is populated
	// exclusively during a CmdSet transaction. Like the Key field, it is a zero-copy
	// sub-slice pointing directly to the active TCP connection buffer frame.
	Value []byte

	// TTL defines the optional lifetime configuration extracted from the relational query
	// parameters via an allocation-free inline integer parser.
	// A value of 0 indicates persistent storage without automatic background eviction.
	TTL time.Duration
}

ParsedQuery is a completely flat, stack-allocated abstraction layer representing the finalized execution intent extracted by the relational byte-scanner.

DESIGN GUARANTEE: To maintain the core requirement of strict zero-allocation performance during the hot parsing path, this struct does not contain pointers, strings, or dynamic heap-escaped objects. All fields are either inlined values or zero-copy sub-slices.

func ParseQuery

func ParseQuery(raw []byte, logger log.Logger) (ParsedQuery, error)

ParseQuery orchestrates the allocation-free scanning of a raw query byte-slice. It routes the relational SQL dialect intents into standard key-value primitives.

DESIGN NOTE: To survive unthrottled CPU load, all child matchers work entirely inline on the 'raw' memory segment without duplicating slices or creating heap-escaped objects.