// Package db is the PostgreSQL persistence layer for dolt.sr.ht. It maps the
// repository, access (ACL) and dolt_key tables to core value types with plain
// database/sql and $n placeholders (no ORM), and enforces the listing/effective
// -access rules that the pure core.Allowed matrix cannot express in SQL.
//
// Design: a Store wraps a Querier — an interface satisfied by *sql.DB, *sql.Tx
// and *sql.Conn alike. This gives us two things the task requires at once:
//
//   - Context-first, middleware-compatible signatures. Production callers build
//     a Store from the connection that core-go's database middleware injects
//     into the request context (see FromContext, which reads the same *sql.DB
//     that database.Middleware installed). Every method takes ctx first and
//     threads it into the query for cancellation.
//
//   - Trivial test injection. Tests call NewStore(db) with a plain *sql.DB, no
//     HTTP context required.
//
// Because the wrapped value is an interface, a Store can be re-bound to an
// open transaction with WithTx(tx): the multi-statement create-repo flow (INSERT
// the row, then write the on-disk NBS store, rolling back both on failure) runs
// every query on the caller's *sql.Tx while sharing the exact same method set.
package db

import (
	"context"
	"database/sql"
	"errors"

	"git.sr.ht/~sircmpwn/core-go/database"
)

// Querier is the common subset of *sql.DB, *sql.Tx and *sql.Conn used by this
// package. Binding a Store to any of them keeps every method identical whether
// it runs standalone (autocommit) or inside a caller-managed transaction.
type Querier interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

// Store is the entry point for all queries in this package.
type Store struct {
	q Querier
}

// NewStore builds a Store over a database handle (or any Querier). Tests pass a
// plain *sql.DB; production wiring passes the shared pool.
func NewStore(q Querier) *Store {
	return &Store{q: q}
}

// FromContext builds a Store over the *sql.DB that core-go's database.Middleware
// installed in ctx. It panics (via database.DBForContext) if no database is
// present in the context — a programming error, never a runtime condition to
// recover from. We wrap the pooled *sql.DB rather than checking out a *sql.Conn
// (database.ForContext) so the Store has no connection to leak; the pool manages
// connection lifetime and ctx still bounds each query.
func FromContext(ctx context.Context) *Store {
	return &Store{q: database.DBForContext(ctx)}
}

// WithTx returns a Store that runs every query on tx instead of the pool. Used
// by the repository create flow, which must coordinate the SQL insert with the
// on-disk store creation under one transaction.
func (s *Store) WithTx(tx *sql.Tx) *Store {
	return &Store{q: tx}
}

// Typed errors returned by this package. Callers match them with errors.Is.
var (
	// ErrNotFound is returned when a lookup, update or delete matched no row.
	ErrNotFound = errors.New("db: not found")
	// ErrNameTaken is returned by CreateRepo when the owner already has a
	// repository with the requested name (uq_repo_owner_id_name violation).
	ErrNameTaken = errors.New("db: repository name already taken")
	// ErrKeyExists is returned by InsertKey when the key id (kid) is already
	// registered (dolt_key.kid UNIQUE violation).
	ErrKeyExists = errors.New("db: dolt key already registered")
)

// rowScanner is satisfied by both *sql.Row and *sql.Rows.
type rowScanner interface {
	Scan(dest ...any) error
}