anchorage/internal/pkg/store/store.go

// Package store defines the interfaces anchorage uses to reach its
// source-of-truth Postgres database. Every domain package (org, pin,
// token, ...) depends on the interface here, never on the concrete
// pgx-backed implementation in store/postgres. This keeps the domain
// layer testable with in-memory fakes.
package store

import (
	"context"
	"errors"
	"time"

	"anchorage/internal/pkg/ids"
)

// ErrNotFound is the canonical "row not present" sentinel. Concrete
// implementations translate driver-specific errors (pgx.ErrNoRows, etc.)
// into this.
var ErrNotFound = errors.New("store: not found")

// ErrConflict is returned when a write violates a uniqueness invariant
// the caller should handle (duplicate slug, duplicate email, existing
// live pin with the same org+cid).
var ErrConflict = errors.New("store: conflict")

// Store is the root aggregate interface. A single implementation pins
// all sub-stores to the same Postgres pool and transaction context so
// composite operations can be atomic.
type Store interface {
	Orgs() OrgStore
	Users() UserStore
	Memberships() MembershipStore
	Tokens() TokenStore
	Nodes() NodeStore
	Pins() PinStore
	Audit() AuditStore

	// WithOrgContext returns a context whose queries run with the
	// anchorage.org_id GUC set, so Postgres RLS applies. The returned
	// context MUST be passed to every subsequent Store call inside the
	// same request so the GUC is honored. Concrete implementations use
	// it to set the GUC per pool connection / transaction.
	WithOrgContext(ctx context.Context, orgID ids.OrgID) (context.Context, error)

	// Tx runs fn inside a Postgres transaction. The closure receives a
	// tx-scoped context (so per-statement cancellation stays tied to the
	// tx's lifetime and any GUC set on the tx is honored) and a Store
	// whose sub-stores share that single tx handle.
	Tx(ctx context.Context, fn func(txCtx context.Context, tx Store) error) error
}

// Org is the domain-level organisation record.
type Org struct {
	ID        ids.OrgID
	Slug      string
	Name      string
	CreatedAt time.Time
	UpdatedAt time.Time
}

// OrgStore holds organisations.
type OrgStore interface {
	Create(ctx context.Context, id ids.OrgID, slug, name string) (*Org, error)
	GetByID(ctx context.Context, id ids.OrgID) (*Org, error)
	GetBySlug(ctx context.Context, slug string) (*Org, error)
	UpdateName(ctx context.Context, id ids.OrgID, name string) (*Org, error)
	List(ctx context.Context, limit, offset int) ([]*Org, error)
}

// User is the domain-level user record.
type User struct {
	ID           ids.UserID
	AuthentikSub string
	Email        string
	DisplayName  string
	IsSysadmin   bool
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

// UserStore holds users.
type UserStore interface {
	UpsertByAuthentikSub(ctx context.Context, id ids.UserID, sub, email, displayName string, isSysadmin bool) (*User, error)
	GetByID(ctx context.Context, id ids.UserID) (*User, error)
	GetByEmail(ctx context.Context, email string) (*User, error)
	PromoteSysadmin(ctx context.Context, id ids.UserID) error
}

// Membership pairs a user with an org + role.
type Membership struct {
	OrgID   ids.OrgID
	UserID  ids.UserID
	Role    string // "orgadmin" | "member"
	OrgSlug string // populated by List*, empty on raw gets
	OrgName string
	Created time.Time
}

// Role constants.
const (
	RoleOrgAdmin = "orgadmin"
	RoleMember   = "member"
)

// MembershipStore manages the user↔org join.
type MembershipStore interface {
	Add(ctx context.Context, orgID ids.OrgID, userID ids.UserID, role string) error
	Remove(ctx context.Context, orgID ids.OrgID, userID ids.UserID) error
	ListForUser(ctx context.Context, userID ids.UserID) ([]*Membership, error)
}

// APIToken is the metadata record for an issued JWT. The signed JWT
// value itself is never stored — revocation is handled via the denylist.
type APIToken struct {
	JTI        ids.TokenID
	OrgID      ids.OrgID
	UserID     ids.UserID
	Label      string
	Scopes     []string
	ExpiresAt  time.Time
	RevokedAt  *time.Time
	LastUsedAt *time.Time
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

// TokenStore manages API token metadata and the denylist.
type TokenStore interface {
	Create(ctx context.Context, t *APIToken) error
	GetByJTI(ctx context.Context, jti ids.TokenID) (*APIToken, error)
	ListForUser(ctx context.Context, orgID ids.OrgID, userID ids.UserID) ([]*APIToken, error)
	Revoke(ctx context.Context, jti ids.TokenID) error
	TouchLastUsed(ctx context.Context, jti ids.TokenID) error

	AddDenylist(ctx context.Context, jti ids.TokenID, expiresAt time.Time, reason string) error
	IsDenied(ctx context.Context, jti ids.TokenID) (bool, error)
	PruneDenylist(ctx context.Context) error
}

// NodeStatus values.
const (
	NodeStatusUp      = "up"
	NodeStatusDown    = "down"
	NodeStatusDrained = "drained"
)

// Node is a cluster member's registry entry.
type Node struct {
	ID          ids.NodeID
	DisplayName string
	Multiaddrs  []string
	RPCURL      string
	Status      string
	LastSeenAt  time.Time
	JoinedAt    time.Time
	UpdatedAt   time.Time
}

// NodeStore manages the cluster registry.
type NodeStore interface {
	Upsert(ctx context.Context, n *Node) error
	Get(ctx context.Context, id ids.NodeID) (*Node, error)
	ListAll(ctx context.Context) ([]*Node, error)
	ListLive(ctx context.Context) ([]*Node, error)
	TouchHeartbeat(ctx context.Context, id ids.NodeID) error
	MarkStaleDown(ctx context.Context, staleAfter time.Duration) ([]ids.NodeID, error)
	Drain(ctx context.Context, id ids.NodeID) error
	Uncordon(ctx context.Context, id ids.NodeID) error
}

// PinStatus values (matching the IPFS Pinning API spec).
const (
	PinStatusQueued  = "queued"
	PinStatusPinning = "pinning"
	PinStatusPinned  = "pinned"
	PinStatusFailed  = "failed"
)

// Pin is the logical pin record (what the API exposes as PinStatus).
type Pin struct {
	RequestID     ids.PinID
	OrgID         ids.OrgID
	CID           string
	Name          *string
	Meta          map[string]any
	Origins       []string
	Status        string
	FailureReason *string
	Created       time.Time
	UpdatedAt     time.Time
}

// Placement is the per-node scheduling row for a pin.
type Placement struct {
	RequestID     ids.PinID
	NodeID        ids.NodeID
	Status        string
	FailureReason *string
	Attempts      int
	Fence         int64
	CreatedAt     time.Time
	UpdatedAt     time.Time
	// Multiaddrs is populated by joined reads; empty on raw fetches.
	Multiaddrs []string
}

// PinFilter is the spec-compliant filter surface for GET /v1/pins.
//
// Every field is optional; empty values disable that clause. `Match` is
// interpreted only when `Name` is set:
//
//	"exact"    — case-sensitive equality
//	"iexact"   — case-insensitive equality (default when name is set)
//	"partial"  — case-sensitive substring
//	"ipartial" — case-insensitive substring
//
// Before and After are both inclusive of their endpoint semantics:
// `after <= created < before`.
type PinFilter struct {
	CIDs   []string
	Name   string
	Match  string
	Status []string
	Before *time.Time
	After  *time.Time
	Meta   map[string]any
	Limit  int
	Offset int
}

// PinStore manages pins and their placements + refcounts.
type PinStore interface {
	Create(ctx context.Context, p *Pin) error
	Get(ctx context.Context, orgID ids.OrgID, requestID ids.PinID) (*Pin, error)
	// GetByRequestID fetches a pin without an org filter.
	//
	// This is used by the scheduler / rebalancer / sweeper which walk
	// placements cluster-wide and need to look up the parent pin without
	// already knowing its org. Do not use from the HTTP API path —
	// routes there are tenant-scoped and must go through Get(orgID, rid).
	GetByRequestID(ctx context.Context, requestID ids.PinID) (*Pin, error)
	GetLiveByCID(ctx context.Context, orgID ids.OrgID, cid string) (*Pin, error)
	UpdateStatus(ctx context.Context, requestID ids.PinID, status string, failureReason *string) error
	Delete(ctx context.Context, orgID ids.OrgID, requestID ids.PinID) error
	List(ctx context.Context, orgID ids.OrgID, limit, offset int) ([]*Pin, error)
	// Filter runs the spec's filtered list. An empty PinFilter is
	// equivalent to List with default pagination.
	Filter(ctx context.Context, orgID ids.OrgID, f PinFilter) ([]*Pin, error)
	// Replace swaps a pin's CID / name / meta / origins atomically.
	// Caller is responsible for reshuffling placements + refcounts
	// inside the same transaction (the CID change means the existing
	// pin_refcount rows are stale).
	Replace(ctx context.Context, orgID ids.OrgID, requestID ids.PinID, newCID string, name *string, meta map[string]any, origins []string) (*Pin, error)

	InsertPlacement(ctx context.Context, requestID ids.PinID, nodeID ids.NodeID, fence int64) (*Placement, error)
	GetPlacement(ctx context.Context, requestID ids.PinID, nodeID ids.NodeID) (*Placement, error)
	ListPlacements(ctx context.Context, requestID ids.PinID) ([]*Placement, error)
	ListPlacementsForNode(ctx context.Context, nodeID ids.NodeID, status string) ([]*Placement, error)
	UpdatePlacementFenced(ctx context.Context, requestID ids.PinID, nodeID ids.NodeID, status string, failureReason *string, fence int64) (int64, error)
	ReplacePlacement(ctx context.Context, requestID ids.PinID, oldNode, newNode ids.NodeID) (*Placement, error)
	StuckPlacements(ctx context.Context, stuckAfter time.Duration) ([]Placement, error)

	IncRefcount(ctx context.Context, nodeID ids.NodeID, cid string) error
	DecRefcount(ctx context.Context, nodeID ids.NodeID, cid string) (int, error)
	DeleteRefcountIfZero(ctx context.Context, nodeID ids.NodeID, cid string) error

	// CountPlacementsByStatus returns a histogram of placement rows
	// grouped by status. Used by the Prometheus gauge refresh loop;
	// unqueried statuses are omitted from the map (a zero gauge is the
	// Prometheus convention).
	CountPlacementsByStatus(ctx context.Context) (map[string]int, error)
}

// AuditEntry is a single audit_log row.
type AuditEntry struct {
	ID            int64
	OrgID         *ids.OrgID
	ActorUserID   *ids.UserID
	ActorTokenJTI *string
	Action        string
	Target        string
	Result        string // "ok" | "error"
	Detail        map[string]any
	Created       time.Time
}

// AuditStore is append-only. Writes must be fire-and-forget-safe —
// callers don't want audit failures to fail user requests, so the
// concrete implementation should log rather than return on error paths
// where appropriate.
type AuditStore interface {
	Insert(ctx context.Context, e *AuditEntry) error
	List(ctx context.Context, orgID ids.OrgID, limit, offset int) ([]*AuditEntry, error)
}