sqlrite-engine 0.10.0

// Package sqlrite is a `database/sql`-compatible driver for the
// SQLRite embedded database engine.
//
// Usage:
//
//	import (
//	    "database/sql"
//	    _ "github.com/joaoh82/rust_sqlite/sdk/go"
//	)
//
//	db, err := sql.Open("sqlrite", "foo.sqlrite")
//	// or: sql.Open("sqlrite", ":memory:")
//
// All standard `database/sql` operations work — Exec, Query, QueryRow,
// transactions via Begin/Commit/Rollback on *sql.Tx. Rows are scanned
// into Go types via `rows.Scan(&id, &name, ...)`.
//
// # How it's wired
//
// This package is a thin cgo shim over the C FFI crate (sqlrite-ffi)
// at ../../sqlrite-ffi. At build time cgo compiles sqlrite.h (the
// cbindgen-generated header) and links the `libsqlrite_c` dynamic
// library. Phase 6i ships prebuilt `libsqlrite_c` tarballs (Linux
// x86_64/aarch64, macOS aarch64, Windows x86_64) on every release —
// see the GitHub Release at sdk/go/v<V>. Developers building from
// a repo clone need `cargo build --release -p sqlrite-ffi` first
// so the shared library exists locally.
//
// # Parameter binding
//
// Like the other SDKs, parameter binding isn't yet in the engine
// (deferred to Phase 5a.2). The driver accepts the `database/sql`
// signature for forward compat, but any non-empty args slice returns
// a clear error. Inline values into the SQL for the moment.
package sqlrite

/*
// Point cgo at the FFI crate's header + the cargo target dir. Paths
// are relative to this Go file (${SRCDIR}). Developers checking out
// the repo need to `cargo build --release -p sqlrite-ffi` once
// before `go test`. End users don't need the Rust toolchain — Phase
// 6i attaches per-platform `libsqlrite_c` tarballs to every Go
// release at `sdk/go/v<V>`; extract one and point `CGO_CFLAGS` /
// `CGO_LDFLAGS` at the unpacked include/ + lib/ dirs.
#cgo CFLAGS: -I${SRCDIR}/../../sqlrite-ffi/include
#cgo LDFLAGS: -L${SRCDIR}/../../target/release -lsqlrite_c

// Embed an rpath pointing at the cargo target dir so `go test` /
// `go run` find libsqlrite_c without any DYLD_LIBRARY_PATH dance.
// Production builds will replace this rpath with a location that
// matches where the library ships (e.g. /usr/local/lib).
#cgo linux LDFLAGS: -Wl,-rpath=${SRCDIR}/../../target/release
#cgo darwin LDFLAGS: -Wl,-rpath,${SRCDIR}/../../target/release

#include <stdlib.h>
#include "sqlrite.h"
*/
import "C"

import (
	"context"
	"database/sql"
	"database/sql/driver"
	"errors"
	"fmt"
	"path/filepath"
	"sync"
	"unsafe"
)

// ---------------------------------------------------------------------------
// Driver registration

// DriverName is the name callers pass to `sql.Open`.
const DriverName = "sqlrite"

func init() {
	sql.Register(DriverName, &sqlriteDriver{})
}

type sqlriteDriver struct{}

// Open implements `driver.Driver`. `name` is the database path (or
// `":memory:"` for a transient in-memory DB, matching SQLite).
func (d *sqlriteDriver) Open(name string) (driver.Conn, error) {
	return newConn(name, false)
}

// OpenReadOnly is a package-level escape hatch — users who want a
// read-only handle can call this directly instead of going through
// `sql.Open`. The `database/sql` API doesn't carry a read-only flag
// through Open, so we offer this as a side door: internally it
// builds a `driver.Connector` that opens each new conn in read-
// only mode, then hands the resulting `*sql.DB` back to the caller.
func OpenReadOnly(name string) *sql.DB {
	return sql.OpenDB(&roConnector{name: name})
}

type roConnector struct{ name string }

// Connect matches driver.Connector. `context.Context` is accepted
// for the signature but unused — the engine has no cancellation
// hook yet.
func (c *roConnector) Connect(_ context.Context) (driver.Conn, error) {
	return newConn(c.name, true)
}
func (c *roConnector) Driver() driver.Driver { return &sqlriteDriver{} }

// ---------------------------------------------------------------------------
// Helpers

// lastError pulls the thread-local last-error string from the FFI.
// Returns an empty string if no error is pending.
func lastError() string {
	p := C.sqlrite_last_error()
	if p == nil {
		return ""
	}
	return C.GoString(p)
}

// Status is a Go-side alias for the C `SqlriteStatus` enum. cgo
// exposes the enum as `uint32` by default (rather than a named type),
// so we work in uint32 internally and compare against the exported
// constants below. The values match the C header byte-for-byte.
type Status uint32

const (
	statusOk              Status = 0
	statusError           Status = 1
	statusInvalidArgument Status = 2
	// Phase 11.7 — retryable-error codes the C FFI surfaces from
	// `BEGIN CONCURRENT` commit conflicts. See `ErrBusy` /
	// `ErrBusySnapshot` below for the Go-side sentinels callers
	// match against.
	statusBusy         Status = 5
	statusBusySnapshot Status = 6
	statusDone         Status = 101
	statusRow          Status = 102
)

// Phase 11.7 — retryable error sentinels exposed to Go callers.
// Match against them with `errors.Is(err, sqlrite.ErrBusy)` /
// `errors.Is(err, sqlrite.ErrBusySnapshot)` to drive a retry
// loop:
//
//	for {
//	    tx, err := db.Begin()
//	    if err != nil { return err }
//	    // ... do work, then:
//	    err = tx.Commit()
//	    if err == nil { break }
//	    if errors.Is(err, sqlrite.ErrBusy) ||
//	        errors.Is(err, sqlrite.ErrBusySnapshot) {
//	        // tx was already rolled back by the engine
//	        continue
//	    }
//	    return err
//	}
//
// Use [IsRetryable] for a kind-agnostic check.
var (
	// ErrBusy is returned when a `BEGIN CONCURRENT` commit hits a
	// row-level write-write conflict. The transaction has already
	// been rolled back; the caller should retry the whole
	// transaction with a fresh `BEGIN CONCURRENT`.
	ErrBusy = errors.New("sqlrite: busy (write-write conflict; transaction rolled back, retry)")

	// ErrBusySnapshot is returned when a `BEGIN CONCURRENT` read
	// sees a row that has been superseded after the transaction's
	// snapshot was taken. Same retry semantics as `ErrBusy`.
	ErrBusySnapshot = errors.New("sqlrite: busy snapshot (snapshot stale; transaction rolled back, retry)")
)

// IsRetryable reports whether `err` chains an `ErrBusy` or
// `ErrBusySnapshot` and should therefore be retried by the
// caller. Use it instead of comparing against individual
// sentinels so a future retryable variant (e.g. lock-wait
// timeout) doesn't force a caller-side change.
func IsRetryable(err error) bool {
	return errors.Is(err, ErrBusy) || errors.Is(err, ErrBusySnapshot)
}

// wrapErr returns a Go error when the status code is nonzero. Use
// after any `sqlrite_*` call that can fail.
//
// Phase 11.7 — retryable statuses surface as errors that wrap the
// matching sentinel (`ErrBusy` / `ErrBusySnapshot`) so callers can
// use `errors.Is` to branch their retry loops without parsing the
// message.
func wrapErr(status Status, op string) error {
	if status == statusOk {
		return nil
	}
	msg := lastError()
	if msg == "" {
		msg = fmt.Sprintf("SQLRite status %d", uint32(status))
	}
	switch status {
	case statusBusy:
		return fmt.Errorf("sqlrite: %s: %s: %w", op, msg, ErrBusy)
	case statusBusySnapshot:
		return fmt.Errorf("sqlrite: %s: %s: %w", op, msg, ErrBusySnapshot)
	default:
		return fmt.Errorf("sqlrite: %s: %s", op, msg)
	}
}

// cString converts a Go string into a C-allocated NUL-terminated
// copy the caller must `C.free`.
func cString(s string) *C.char { return C.CString(s) }

// isSelect is a coarse heuristic: trim leading whitespace/comments
// and check if the statement starts with `select`. Used to pick
// between `sqlrite_execute` (no rows) and `sqlrite_query` (rows).
// The engine also reports the statement type via its parser, but
// exposing that through the C FFI would add another round-trip per
// call — not worth it for this level of granularity.
func isSelect(sql string) bool {
	for i := 0; i < len(sql); i++ {
		c := sql[i]
		if c == ' ' || c == '\t' || c == '\n' || c == '\r' {
			continue
		}
		// Strip `--` line comments. Block comments (`/* */`) aren't
		// worth the complexity here — users almost never put those
		// before SELECT in practice.
		if c == '-' && i+1 < len(sql) && sql[i+1] == '-' {
			for i < len(sql) && sql[i] != '\n' {
				i++
			}
			continue
		}
		remaining := sql[i:]
		if len(remaining) < 6 {
			return false
		}
		head := remaining[:6]
		return eqFold(head, "select")
	}
	return false
}

// eqFold is an ASCII-only case-insensitive compare — avoids the
// strings.ToLower allocation for this hot path.
func eqFold(a, b string) bool {
	if len(a) != len(b) {
		return false
	}
	for i := 0; i < len(a); i++ {
		ca, cb := a[i], b[i]
		if ca >= 'A' && ca <= 'Z' {
			ca += 'a' - 'A'
		}
		if cb >= 'A' && cb <= 'Z' {
			cb += 'a' - 'A'
		}
		if ca != cb {
			return false
		}
	}
	return true
}

// rejectParamsForNow is the uniform "we don't do parameter binding
// yet" response. Accepted: nil / empty. Anything else is an error.
func rejectParamsForNow(args []driver.Value) error {
	if len(args) == 0 {
		return nil
	}
	return errors.New(
		"sqlrite: parameter binding is not yet supported — inline values into the SQL " +
			"(a future Phase 5a.2 release will add real binding)",
	)
}

func rejectNamedParamsForNow(args []driver.NamedValue) error {
	if len(args) == 0 {
		return nil
	}
	return errors.New(
		"sqlrite: parameter binding is not yet supported — inline values into the SQL " +
			"(a future Phase 5a.2 release will add real binding)",
	)
}

// freeCString is a typed alias so call sites read cleanly.
func freeCString(p *C.char) { C.free(unsafe.Pointer(p)) }

// ---------------------------------------------------------------------------
// Phase 11.11c — process-level path registry for file-backed siblings.
//
// The engine's `Connection::open` takes `flock(LOCK_EX)` on the WAL
// sidecar, so the *second* `sqlrite_open` for the same path in the
// same process would deadlock with itself. `database/sql` makes this
// easy to hit: a single `sql.DB`'s pool spins up additional `Conn`s
// on demand by calling `driver.Open` again, and applications routinely
// hold more than one `*sql.DB` against the same file.
//
// We thread every file-backed read-write `newConn` call through a
// process-level registry keyed by canonical absolute path. The first
// caller pays for a real `sqlrite_open` and the resulting handle is
// stashed as a hidden "primary" in the registry. Subsequent callers
// (within the same `sql.DB` pool or across instances) mint a sibling
// off that primary via `sqlrite_connect_sibling` — sharing the
// `Arc<Mutex<Database>>` underneath, so they all see the same tables
// and can each hold their own `BEGIN CONCURRENT`. The registry holds
// a refcount of outstanding siblings; when the last one closes, the
// registry closes the primary and drops the entry.
//
// **Scope (v0).** Read-only opens and `:memory:` opens skip the
// registry: a read-only open takes a shared lock that can coexist
// with other readers but conflicts with any writer in the same
// process, and `:memory:` databases are isolated by design.
// Cross-pool sharing for read-only handles is a future follow-up if
// anyone hits the use case.
//
// **Lock order.** Two locks are in play: each `*conn`'s `c.mu`, and
// the registry's `registryMu`. Acquisition order is always
// `c.mu` → `registryMu`, never the reverse. `newConn` only holds
// `registryMu`; `conn.Close` takes `c.mu` first, then `registryMu`.

type sharedEntry struct {
	// Hidden primary handle owned by the registry. Never exposed
	// to a `*conn`; every `*conn` gets a sibling minted off it.
	primary *C.SqlriteConnection
	// Number of outstanding siblings minted off this primary.
	// When this hits zero we close the primary and remove the
	// entry.
	refcount int32
}

var (
	registryMu sync.Mutex
	// canonical absolute path → entry.
	pathRegistry = map[string]*sharedEntry{}
)

// canonicalPath returns the absolute, lexically-cleaned form of
// `name`. We use this as the registry key so two `sql.Open` calls
// with different relative paths but the same target resolve to the
// same entry. Symlinks are *not* resolved — `filepath.Abs` is
// path-syntactic only. Callers who want symlink-equality should
// pass an `os.EvalSymlinks`-ed path; for v0 that's their problem,
// not ours.
func canonicalPath(name string) (string, error) {
	abs, err := filepath.Abs(name)
	if err != nil {
		return "", fmt.Errorf("sqlrite: canonicalize %q: %w", name, err)
	}
	return filepath.Clean(abs), nil
}

// acquireSiblingHandle is the entry point newConn calls for
// file-backed read-write opens. Returns the sibling handle the
// caller should own + the canonical path the caller stashes on
// the `*conn` so Close can find the right entry.
func acquireSiblingHandle(name string) (*C.SqlriteConnection, string, error) {
	canonical, err := canonicalPath(name)
	if err != nil {
		return nil, "", err
	}

	registryMu.Lock()
	defer registryMu.Unlock()

	entry, ok := pathRegistry[canonical]
	if !ok {
		// First open for this path. Create the primary as the
		// registry's hidden owner. If this `sqlrite_open` fails
		// (file doesn't exist + we can't create it, locked by
		// another process, …), surface the error and leave the
		// registry untouched.
		cName := cString(canonical)
		defer freeCString(cName)
		var primary *C.SqlriteConnection
		status := Status(C.sqlrite_open(cName, &primary))
		if err := wrapErr(status, "open"); err != nil {
			return nil, "", err
		}
		entry = &sharedEntry{primary: primary, refcount: 0}
		pathRegistry[canonical] = entry
	}

	// Mint a sibling for this caller off the primary.
	var sibling *C.SqlriteConnection
	status := Status(C.sqlrite_connect_sibling(entry.primary, &sibling))
	if err := wrapErr(status, "connect_sibling"); err != nil {
		// Sibling creation failed. If this entry has no other
		// outstanding siblings, the primary is dead weight —
		// close it and drop the entry so a future `newConn`
		// doesn't try to mint a sibling off a stale handle.
		if entry.refcount == 0 {
			C.sqlrite_close(entry.primary)
			delete(pathRegistry, canonical)
		}
		return nil, "", err
	}

	entry.refcount++
	return sibling, canonical, nil
}

// releaseSiblingHandle is called from `conn.Close` for registered
// conns. Drops the refcount; when it hits zero, closes the hidden
// primary and removes the entry.
func releaseSiblingHandle(canonical string) {
	registryMu.Lock()
	defer registryMu.Unlock()

	entry, ok := pathRegistry[canonical]
	if !ok {
		// Defensive: the entry should always exist here.
		// If it doesn't, we're either double-closing (in
		// which case there's nothing to do) or the registry
		// is corrupted (in which case the FFI's own asserts
		// would catch it on the next sibling open). Drop
		// silently.
		return
	}
	entry.refcount--
	if entry.refcount <= 0 {
		C.sqlrite_close(entry.primary)
		delete(pathRegistry, canonical)
	}
}

// registryHandleCount returns the number of outstanding siblings
// for `path` (canonicalized internally). Returns 0 for unknown
// paths. Used by the tests; not part of the public API.
//
//nolint:deadcode // exported via go:linkname-style for test access
func registryHandleCount(path string) int32 {
	canonical, err := canonicalPath(path)
	if err != nil {
		return 0
	}
	registryMu.Lock()
	defer registryMu.Unlock()
	if entry, ok := pathRegistry[canonical]; ok {
		return entry.refcount
	}
	return 0
}