store

package
v0.9.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 14, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package store defines the persistent storage boundary for EasyVCS.

EasyVCS uses a single central SQL database (default ~/.easyvcs/easyvcs.db, overridable via EASYVCS_HOME). All repositories live in that one database, keyed by a (namespace, name) pair. Content-addressed objects are global and deduplicated across repositories; revisions, snapshots, and refs are scoped to a repository via a repo id.

The semantic layer depends on the repo-scoped RepoStore interface, never on a concrete backend. This lets the same code run against SQLite (local) or Postgres (server) with no changes, and no cgo.

Index

Constants

View Source
const (
	KindSQLite   = "sqlite"
	KindPostgres = "postgres"
	KindMySQL    = "mysql"
)

Kinds of metadata backends.

View Source
const (
	RoleMaintainer = "maintainer"
	RoleDeveloper  = "developer"
)

Repository roles. The owner is derived from the namespace owner and is not stored as a repo_members row; maintainer/developer are explicit grants.

View Source
const DefaultDBFile = "easyvcs.db"

DefaultDBFile is the file name of the central database inside the home dir.

View Source
const WorkspaceMarkerFile = ".easyvcs-workspace"

WorkspaceMarkerFile is the name of the workspace pointer file placed at a working directory root.

Variables

View Source
var ErrNotFound = errors.New("store: not found")

ErrNotFound is returned when a keyed entity is absent.

View Source
var ErrPackageOwned = errors.New("store: package belongs to another user")

ErrPackageOwned is returned when another user owns the name.

View Source
var ErrRepoExists = errors.New("store: repository already exists")

ErrRepoExists is returned when trying to create a repository that already exists.

View Source
var ErrRepoNotFound = errors.New("store: repository not found")

ErrRepoNotFound is returned when a repository is absent.

View Source
var ErrRevisionChanged = errors.New("store: revision changed concurrently")

ErrRevisionChanged is returned by an optimistic update (CAS) when a revision's current hash no longer matches the value the caller read, meaning another writer modified the revision concurrently. Callers should retry.

View Source
var ErrScopeNotYours = errors.New("store: scope does not belong to you (create the namespace/repo first)")

ErrScopeNotYours is returned when the npm-style scope (@org/…) has no org evidence in the caller's namespaces.

View Source
var ErrTokenNotFound = errors.New("store: token not found")

ErrTokenNotFound is returned when a token is unknown.

View Source
var ErrUsernameTaken = errors.New("store: username already exists")

ErrUsernameTaken is returned when creating a user that already exists.

Functions

func DBPath

func DBPath() string

DBPath returns the path to the central database file.

func HomeDir

func HomeDir() string

HomeDir returns the EasyVCS home directory (default ~/.easyvcs, overridable via EASYVCS_HOME).

func NamespaceOfName added in v0.7.0

func NamespaceOfName(format, repository string) string

NamespaceOfName extracts the ownership namespace of a registry name per its native protocol convention: npm "@org/name" → "org"; OCI and generic "a/b/..." paths → the first path segment; flat names → "" (no namespace — such protocols cannot be claimed under org evidence and rely on the protocol adapter requiring a namespace).

func SnapshotHashFor

func SnapshotHashFor(s *Snapshot) object.ID

SnapshotHashFor computes the content-addressed revision hash for a snapshot. It is the store-level canonical form (matching the revision package's snapshotID): the hash is derived from the revision id, tree, parents, description, and author. It is exported so the store can recompute a hash when re-keying a snapshot (e.g. forked revisions get a fresh identity).

func WriteMarker

func WriteMarker(dir string, m *WorkspaceMarker) error

WriteMarker writes a workspace marker file at the given directory root. If the marker does not already record a store location (Home/DSN), the process's HomeDir() is recorded so the workspace is self-describing; a caller that binds a workspace to a different store sets Home/DSN explicitly beforehand.

Types

type AuditEvent

type AuditEvent struct {
	Timestamp int64
	Action    string // "advertise" | "fetch" | "push"
	Namespace string
	Repo      string
	UserID    *int64
	IP        string
	Outcome   string // "ok" | "denied" | "error"
	Detail    string
}

AuditEvent is a plain append-only record of an access attempt.

type Author

type Author struct {
	Name  string
	Email string
}

Author is a named identity.

func (Author) String

func (a Author) String() string

String renders an author as "Name <email>".

type CentralStore

type CentralStore struct {
	// contains filtered or unexported fields
}

sqlDialect is defined in driver.go; it provides both the raw *sql.DB handle (for SetWAL and legacy helpers) and the GORM session used for model queries. CentralStore is the single-database store. It holds many repositories, each identified by (namespace, name). Objects are global (content-addressed and deduplicated); metadata tables are scoped by a repo id.

func Open

func Open(path string) (*CentralStore, error)

Open opens the central store at the given SQLite file path (legacy helper).

func OpenDefault

func OpenDefault() (*CentralStore, error)

OpenDefault opens the central store at the default SQLite path.

func OpenDriver

func OpenDriver(cfg DriverConfig) (*CentralStore, error)

OpenDriver opens the central store on the configured backend. The semantic layer (revision/merge/transfer) is agnostic; only this boundary changes. Storage is now GORM-backed so the three dialects share one code path.

func OpenStoreForMarker

func OpenStoreForMarker(m *WorkspaceMarker) (*CentralStore, error)

OpenStoreForMarker opens the central store that a workspace marker belongs to. The marker must record a store location (Home for a sqlite store, or DSN as an override). Unlike the legacy fallback, there is no silent reliance on the process EASYVCS_HOME: an empty Home and DSN is treated as an invalid marker.

func (*CentralStore) AddComment

func (s *CentralStore) AddComment(mrID int64, authorID *int64, body, path string) (*Comment, error)

AddComment appends a comment to an MR.

func (*CentralStore) AddReview

func (s *CentralStore) AddReview(mrID int64, reviewerID *int64, state, body string) (*Review, error)

AddReview appends a review to an MR.

func (*CentralStore) AgentBinding added in v0.8.2

func (s *CentralStore) AgentBinding(userID int64) (agentTenant, agentToken string, err error)

AgentBinding returns the user's bound agent tenant id + credential.

func (*CentralStore) AgentToken added in v0.8.0

func (s *CentralStore) AgentToken(userID int64) (string, error)

AgentToken returns the user's agent credential ("" when unset).

func (*CentralStore) AllMirrors

func (s *CentralStore) AllMirrors() ([]*Repo, RepoMetaMap, error)

AllMirrors lists every read-only mirror repository (scheduler). The mirror token is decrypted (RepoMeta.UpdateMirrorMeta encrypts on write; this raw row read must mirror that).

func (*CentralStore) AllPushMirrors

func (s *CentralStore) AllPushMirrors() ([]*PushMirror, error)

AllPushMirrors lists every push-mirror across all repositories (scheduler). Tokens are decrypted for the scheduler's authenticated pushes.

func (*CentralStore) AuthorizePublish added in v0.7.0

func (s *CentralStore) AuthorizePublish(ctx context.Context, format, repository string, userID int64) error

AuthorizePublish implements the registry Ownership contract: a user may publish (format, repository) when it already owns the name, or when the name is unclaimed AND the name's namespace part is one the user owns (npm @scope or OCI namespace mapped onto easyvcs namespaces).

func (*CentralStore) CanRead added in v0.7.0

func (s *CentralStore) CanRead(ctx context.Context, format, repository string, userID int64) bool

CanRead implements the registry Ownership contract: public and unclaimed names are readable by everyone; private names only by the owning user.

func (*CentralStore) ClaimPackage added in v0.7.0

func (s *CentralStore) ClaimPackage(format, repository string, userID int64) error

ClaimPackage records userID as the owner of a previously unclaimed name. Returns ErrPackageOwned when the name is already owned by someone else.

func (*CentralStore) Close

func (s *CentralStore) Close() error

Close closes the underlying database.

func (*CentralStore) Create

func (s *CentralStore) Create(r RepoRef) (*Repo, error)

Create creates a new repository and returns a repo-scoped handle. The namespace is globally unique and owned by the user in RepoRef.Owner; owner 0 creates an unowned, public dev repo (no ACLs). The owner is denormalized into owner_user_id.

func (*CentralStore) CreateMergeRequest

func (s *CentralStore) CreateMergeRequest(repoID int64, mr *MergeRequest) (*MergeRequest, error)

CreateMergeRequest inserts a new MR and returns it. IID is assigned monotonically per repo.

func (*CentralStore) CreateMirror

func (s *CentralStore) CreateMirror(r RepoRef, meta RepoMeta) (*Repo, error)

CreateMirror creates a read-only mirror repository and returns its handle.

func (*CentralStore) CreateToken

func (s *CentralStore) CreateToken(token string, userID int64, level string) (*Token, error)

CreateToken inserts a bearer token for a user. The token is stored as its SHA-256 hash; the returned Token carries the plaintext for one-time display.

func (*CentralStore) CreateUser

func (s *CentralStore) CreateUser(username, displayName string) (*User, error)

CreateUser inserts a new user. Creating the first user closes the instance (anonymous access stops being allowed).

func (*CentralStore) Delete

func (s *CentralStore) Delete(r RepoRef) error

Delete removes a repository and all of its scoped metadata. Reviews and comments are removed via a subquery on the repo's MR ids; any failure is returned (no silent partial deletes).

func (*CentralStore) DeleteToken

func (s *CentralStore) DeleteToken(token string) error

DeleteToken removes a token by its secret value.

func (*CentralStore) DeleteUser added in v0.9.0

func (s *CentralStore) DeleteUser(id int64) error

DeleteUser removes a user and every row owned by it: namespaces, repositories (with their metadata), tokens, repo memberships, and package ownership claims.

func (*CentralStore) EnsureNamespace added in v0.9.0

func (s *CentralStore) EnsureNamespace(owner int64, name string) error

EnsureNamespace creates the namespace for its owner when absent (idempotent).

func (*CentralStore) Fork

func (s *CentralStore) Fork(src RepoRef, dst RepoRef) (*Repo, error)

Fork copies a repository's scoped data (snapshots, revisions, refs) plus its hosting metadata into a new (namespace, name), sharing the global object store. The source repository is left untouched. It returns the new repo.

func (*CentralStore) GetMergeRequest

func (s *CentralStore) GetMergeRequest(repoID, iid int64) (*MergeRequest, error)

GetMergeRequest returns an MR by repo + iid.

func (*CentralStore) GetPackageOwner added in v0.7.0

func (s *CentralStore) GetPackageOwner(format, repository string) (*PackageOwner, error)

GetPackageOwner returns the ownership record of a name, or ErrNotFound.

func (*CentralStore) GetUser

func (s *CentralStore) GetUser(id int64) (*User, error)

GetUser returns a user by id.

func (*CentralStore) GetUserByAgentTenant added in v0.9.1

func (s *CentralStore) GetUserByAgentTenant(agentTenant string) (*User, error)

GetUserByAgentTenant resolves the user bound to an abcp-agent tenant id.

func (*CentralStore) GetUserByUsername

func (s *CentralStore) GetUserByUsername(username string) (*User, error)

GetUserByUsername returns a user by username.

func (*CentralStore) GetWorkspaceByPath

func (s *CentralStore) GetWorkspaceByPath(path string) (*WorkspaceRow, error)

GetWorkspaceByPath looks up a workspace row by path.

func (*CentralStore) Init

func (s *CentralStore) Init() error

Init creates the schema via GORM AutoMigrate, generating portable DDL (sqlite / postgres / mysql). Idempotent.

func (*CentralStore) IsOpenInstance

func (s *CentralStore) IsOpenInstance() bool

IsOpenInstance reports whether the instance has no registered users, in which case anonymous READ access is allowed (CLI/dev default). WRITE access is never granted anonymously: the caller must still authenticate.

func (*CentralStore) List

func (s *CentralStore) List() ([]RepoRef, error)

func (*CentralStore) ListAccessible added in v0.9.0

func (s *CentralStore) ListAccessible(userID int64) ([]RepoRef, error)

ListAccessible returns every repository a user may READ: public repos (any owner) plus private repos where the user is the owner or a repo member.

func (*CentralStore) ListAudit

func (s *CentralStore) ListAudit(limit int) ([]AuditEvent, error)

ListAudit returns the most recent audit records (newest first), used for verification/diagnostics.

func (*CentralStore) ListComments

func (s *CentralStore) ListComments(mrID int64) ([]*Comment, error)

ListComments returns comments for an MR.

func (*CentralStore) ListForOwner added in v0.9.0

func (s *CentralStore) ListForOwner(owner int64) ([]RepoRef, error)

ListForOwner returns every repository owned by one user.

func (*CentralStore) ListMergeRequests

func (s *CentralStore) ListMergeRequests(repoID int64, state string) ([]*MergeRequest, error)

ListMergeRequests returns MRs for a repo, optionally filtered by state.

func (*CentralStore) ListNamespacesByOwner added in v0.9.0

func (s *CentralStore) ListNamespacesByOwner(owner int64) ([]*Namespace, error)

ListNamespacesByOwner returns the namespaces owned by a user.

func (*CentralStore) ListRepoMembers added in v0.9.0

func (s *CentralStore) ListRepoMembers(repoID int64) ([]*RepoMember, error)

ListRepoMembers returns the explicit (non-owner) members of a repository.

func (*CentralStore) ListReviews

func (s *CentralStore) ListReviews(mrID int64) ([]*Review, error)

ListReviews returns reviews for an MR.

func (*CentralStore) ListTokens

func (s *CentralStore) ListTokens(userID int64) ([]*Token, error)

ListTokens returns all tokens for a user. The stored value is a SHA-256 hash and is NOT returned; Token.Token is empty (the plaintext is only available from CreateToken at creation time).

func (*CentralStore) ListUsers

func (s *CentralStore) ListUsers() ([]*User, error)

ListUsers returns all users ordered by username.

func (*CentralStore) ListWorkspaces

func (s *CentralStore) ListWorkspaces() ([]*WorkspaceRow, error)

ListWorkspaces returns all registered workspaces.

func (*CentralStore) LookupToken

func (s *CentralStore) LookupToken(token string) (*Token, error)

LookupToken resolves a token string to its user and level. It returns ErrTokenNotFound when the token is unknown. The plaintext token is echoed back in the returned record for interface stability (the caller supplied it).

func (*CentralStore) OpenRepo

func (s *CentralStore) OpenRepo(r RepoRef) (*Repo, error)

OpenRepo opens an existing repository by namespace/name (global). Returns ErrRepoNotFound if missing.

func (*CentralStore) OwnerOfNamespace added in v0.9.0

func (s *CentralStore) OwnerOfNamespace(name string) (int64, error)

OwnerOfNamespace returns the user id owning the namespace (0 when absent).

func (*CentralStore) PutWorkspace

func (s *CentralStore) PutWorkspace(w *WorkspaceRow) error

PutWorkspace registers or updates a workspace row in the central store.

func (*CentralStore) QueryCount

func (s *CentralStore) QueryCount(count *int) error

QueryCount returns the total number of content-addressed objects. It is a convenience for tests to verify global deduplication.

func (*CentralStore) RecordAudit

func (s *CentralStore) RecordAudit(ev AuditEvent) error

RecordAudit appends an audit event to the append-only audit_log table. It never updates or deletes (no undo/reflog semantics).

func (*CentralStore) RemoveRepoMember added in v0.9.0

func (s *CentralStore) RemoveRepoMember(repoID, userID int64) error

RemoveRepoMember revokes a user's role on a repository.

func (*CentralStore) RepoExists

func (s *CentralStore) RepoExists(r RepoRef) (bool, error)

RepoExists reports whether a repository exists (namespace/name is global).

func (*CentralStore) RepoMemberRole added in v0.9.0

func (s *CentralStore) RepoMemberRole(repoID, userID int64) (string, error)

RepoMemberRole returns the explicit role a user holds on a repo ("" when a collaborator grant is absent).

func (*CentralStore) RepoRefByID added in v0.9.1

func (s *CentralStore) RepoRefByID(id int64) (RepoRef, error)

RepoRefByID resolves a repository id to its RepoRef (namespace/name/owner).

func (*CentralStore) ResolveWorkspace

func (s *CentralStore) ResolveWorkspace(dir string) (*WorkspaceMarker, *Repo, error)

FindRepo walks up from dir to locate the repo a workspace belongs to. It returns the workspace marker and the repo-scoped handle, opening the store recorded by the marker (Home/DSN) rather than assuming this store instance. If the marker's repo is missing from its store, an error is returned.

func (*CentralStore) RoleOf added in v0.9.0

func (s *CentralStore) RoleOf(repoID, userID int64) (Role, error)

RoleOf resolves the effective role of userID on a repository. userID 0 is an anonymous caller.

func (*CentralStore) RoleOfRef added in v0.9.0

func (s *CentralStore) RoleOfRef(ref RepoRef, userID int64) (Role, error)

RoleOfRef resolves the effective role of userID on the repo named by ref.

func (*CentralStore) SetAgentBinding added in v0.8.2

func (s *CentralStore) SetAgentBinding(userID int64, agentTenant, agentToken string) error

SetAgentBinding stores the user's bound agent tenant id + credential (empty values are ignored, so a partial update never clears the other).

func (*CentralStore) SetPackageVisibility added in v0.7.0

func (s *CentralStore) SetPackageVisibility(format, repository string, userID int64, visibility string) error

SetPackageVisibility flips a name's visibility (owning user only).

func (*CentralStore) SetRepoMember added in v0.9.0

func (s *CentralStore) SetRepoMember(repoID, userID int64, role string, grantedBy *int64) error

SetRepoMember grants or updates a user's role on a repository. Owner cannot be granted here (the owner is the namespace owner).

func (*CentralStore) SetWAL

func (s *CentralStore) SetWAL() error

SetWAL enables SQLite WAL mode for safe concurrent access across processes (many workspaces sharing one DB), plus a busy timeout so concurrent writers queue instead of failing with SQLITE_BUSY. No-op for Postgres/MySQL.

func (*CentralStore) TenantHasNamespace added in v0.7.0

func (s *CentralStore) TenantHasNamespace(userID int64, namespace string) bool

TenantHasNamespace reports whether a user owns a namespace (registry scope evidence: you may publish @org/… only when you own that namespace).

func (*CentralStore) UpdateMergeRequestState

func (s *CentralStore) UpdateMergeRequestState(repoID, iid int64, state string) error

UpdateMergeRequestState updates an MR state (merged/closed/reopen).

func (*CentralStore) UpdateUser added in v0.9.0

func (s *CentralStore) UpdateUser(id int64, displayName *string, disabled *bool) (*User, error)

UpdateUser patches display name / disabled state.

type Comment

type Comment struct {
	ID       int64
	MRID     int64
	AuthorID *int64
	Body     string
	Path     string
	Created  time.Time
}

Comment is a discussion line on a merge request.

type DriverConfig

type DriverConfig struct {
	Kind string
	DSN  string
}

DriverConfig selects the metadata backend. Kind is "sqlite", "postgres", or "mysql"/"mariadb". All dialects are pure-Go (no cgo): sqlite via glebarez/sqlite (modernc), postgres via pgx, mysql via go-sql-driver.

type MergeRequest

type MergeRequest struct {
	ID           int64
	RepoID       int64
	SourceRepoID int64
	IID          int64
	Title        string
	Description  string
	Source       string // revision id or branch name
	Target       string // revision id or branch name
	State        string // "open" | "merged" | "closed"
	AuthorID     *int64
	Created      time.Time
	Updated      time.Time
}

MergeRequest models a change-tracking request between two revisions. A same-repo MR has SourceRepoID == RepoID; a fork→upstream MR has SourceRepoID pointing at the fork while RepoID is the target (upstream) repository.

type Namespace added in v0.9.0

type Namespace struct {
	Name        string
	OwnerUserID int64
	Created     time.Time
}

Namespace is an org owned by one user. Repositories live under it, so its owner is also the repository owner.

type PackageOwner added in v0.7.0

type PackageOwner struct {
	Format      string
	Repository  string
	OwnerUserID int64
	Visibility  string // "public" | "private"
	Created     time.Time
}

PackageOwner is the ownership record of one registry name.

type PushMirror

type PushMirror struct {
	ID        int64
	RepoID    int64
	Name      string
	URL       string
	Branch    string // branch name to push (default "main")
	Token     string
	LastRev   string // last revision id pushed (dirty detection)
	LastError string
}

PushMirror is a named external git destination that receives a force push of a single branch's tree. A normal (read-write) repository may have several.

type Ref

type Ref struct {
	Name   string
	Kind   RefKind
	Target string // revision id
}

Ref is a named pointer to a revision.

type RefKind

type RefKind string

RefKind distinguishes mutable branchs from immutable tags.

const (
	RefBranch RefKind = "branch"
	RefTag    RefKind = "tag"
)

Ref kinds.

type Remote

type Remote struct {
	Name  string
	URL   string
	Token string
}

Remote is a named URL to another EasyVCS server. Token is the optional bearer token used to authenticate writes against that server.

type RemoteRef

type RemoteRef struct {
	RemoteName string
	Kind       RefKind
	Name       string
	Target     string // revision id on the remote
}

RemoteRef is a snapshot of a remote's ref as last fetched, scoped to a remote name (e.g. "origin.main", kind=branch). This mirrors git's refs/remotes.

type Repo

type Repo struct {
	OwnerUserID int64
	Namespace   string
	Name        string
	// contains filtered or unexported fields
}

Repo is a repo-scoped handle bound to a specific repository in the central store. It implements RepoStore. OwnerUserID is the namespace owner (the repository's owner).

func (*Repo) BeginTx

func (r *Repo) BeginTx() *gorm.DB

BeginTx starts a GORM transaction on the central store.

func (*Repo) Close

func (r *Repo) Close() error

Close is a no-op for the repo handle (the CentralStore is shared).

func (*Repo) DeleteObject

func (r *Repo) DeleteObject(id object.ID) error

DeleteObject removes a single content-addressed object (global). It is used by the GC command to prune objects no longer referenced by any snapshot. The caller is responsible for reachability analysis.

func (*Repo) DeletePushMirror

func (r *Repo) DeletePushMirror(name string) error

DeletePushMirror removes a push-mirror by name.

func (*Repo) DeleteRef

func (r *Repo) DeleteRef(name string) error

DeleteRef removes a ref scoped to this repository.

func (*Repo) DeleteRemote

func (r *Repo) DeleteRemote(name string) error

DeleteRemote removes a remote by name.

func (*Repo) DeleteRemoteRefsForRemote

func (r *Repo) DeleteRemoteRefsForRemote(remoteName string) error

DeleteRemoteRefsForRemote clears all recorded refs for a remote (used when a remote is deleted or force-refreshed).

func (*Repo) GetLastSyncTip

func (r *Repo) GetLastSyncTip(name string) (string, error)

GetLastSyncTip returns the last synced tip for a remote ("" if none).

func (*Repo) GetPushMirror

func (r *Repo) GetPushMirror(name string) (*PushMirror, error)

GetPushMirror returns one push-mirror by name (token decrypted).

func (*Repo) GetRef

func (r *Repo) GetRef(name string) (*Ref, error)

GetRef reads a ref scoped to this repository.

func (*Repo) GetRemote

func (r *Repo) GetRemote(name string) (*Remote, error)

GetRemote returns a remote by name.

func (*Repo) GetRemoteDefaultBranch

func (r *Repo) GetRemoteDefaultBranch(name string) (string, error)

GetRemoteDefaultBranch returns the remote's default branch ("" if none).

func (*Repo) GetRevision

func (r *Repo) GetRevision(id string) (*Revision, error)

GetRevision reads a revision scoped to this repository.

func (*Repo) GetSnapshot

func (r *Repo) GetSnapshot(id object.ID) (*Snapshot, error)

GetSnapshot reads a snapshot scoped to this repository.

func (*Repo) GitCommitForRevision

func (r *Repo) GitCommitForRevision(revID string) (string, error)

GitCommitForRevision returns the last exported commit sha for a revision, if any.

func (*Repo) IsMirror

func (r *Repo) IsMirror() bool

IsMirror reports whether the repository is a read-only external mirror.

func (*Repo) ListPushMirrors

func (r *Repo) ListPushMirrors() ([]*PushMirror, error)

ListPushMirrors lists all push-mirrors for this repo (tokens omitted).

func (*Repo) ListRefs

func (r *Repo) ListRefs() ([]*Ref, error)

ListRefs lists refs scoped to this repository.

func (*Repo) ListRemoteRefs

func (r *Repo) ListRemoteRefs(remoteName string) ([]*RemoteRef, error)

ListRemoteRefs lists all remote refs for this repo (optionally filtered by remote name). Returns refs keyed under the remote (name is bare, e.g. "main").

func (*Repo) ListRemotes

func (r *Repo) ListRemotes() ([]*Remote, error)

ListRemotes lists all remotes for this repository. Tokens are omitted from the returned list to avoid leaking secrets.

func (*Repo) ListRevisions

func (r *Repo) ListRevisions() ([]*Revision, error)

ListRevisions lists revisions scoped to this repository.

func (*Repo) ObjectExists

func (r *Repo) ObjectExists(id object.ID) (bool, error)

ObjectExists reports whether an object is present.

func (*Repo) ObjectIDs

func (r *Repo) ObjectIDs() ([]object.ID, error)

ObjectIDs returns all content-addressed object ids held anywhere in the central store (objects are global and deduplicated across repositories). It is used by clients to advertise "have" objects during fetch/push so a peer only sends objects the destination lacks.

func (*Repo) Owner added in v0.9.0

func (r *Repo) Owner() int64

Owner returns the repository's owner user id (the namespace owner).

func (r *Repo) PutGitLink(revID, commitSHA, ref, side string) error

PutGitLink records a revision<->commit traceability link for the git bridge.

func (*Repo) PutPushMirror

func (r *Repo) PutPushMirror(m *PushMirror) error

PutPushMirror inserts or replaces a push-mirror for this repo. The token is encrypted at rest (EASYVCS_SECRET_KEY; plaintext when unset).

func (*Repo) PutRef

func (r *Repo) PutRef(ref *Ref) error

PutRef stores a ref scoped to this repository.

func (*Repo) PutRefTx

func (r *Repo) PutRefTx(tx *gorm.DB, ref *Ref) error

PutRefTx upserts a ref within an open transaction.

func (*Repo) PutRemote

func (r *Repo) PutRemote(name, url, token string) error

PutRemote registers or updates a remote for this repository. An empty token clears the stored token.

func (*Repo) PutRevision

func (r *Repo) PutRevision(rev *Revision) error

PutRevision stores a revision scoped to this repository.

func (*Repo) PutRevisionTx

func (r *Repo) PutRevisionTx(tx *gorm.DB, rev *Revision) error

PutRevisionTx inserts a revision within an open transaction.

func (*Repo) PutSnapshot

func (r *Repo) PutSnapshot(snap *Snapshot) error

PutSnapshot stores a snapshot scoped to this repository. Parents, author, and description are packed into a single compact meta BLOB (see encoding pkg).

func (*Repo) PutSnapshotTx

func (r *Repo) PutSnapshotTx(tx *gorm.DB, snap *Snapshot) error

PutSnapshotTx inserts a snapshot within an open transaction.

func (*Repo) ReadObject

func (r *Repo) ReadObject(id object.ID) (*object.Object, error)

ReadObject reads a global content-addressed object.

func (*Repo) RepoID

func (r *Repo) RepoID() int64

RepoID returns the numeric repo id used internally.

func (*Repo) RepoMeta

func (r *Repo) RepoMeta() (RepoMeta, error)

RepoMeta returns the hosting metadata for a repository.

func (*Repo) RepoRef

func (r *Repo) RepoRef() RepoRef

RepoRef returns the RepoRef for this handle.

func (*Repo) RevisionForGitCommit

func (r *Repo) RevisionForGitCommit(commitSHA string) (string, error)

RevisionForGitCommit returns the easyvcs revision that a commit sha was imported as, if any.

func (*Repo) SetRemoteDefaultBranch

func (r *Repo) SetRemoteDefaultBranch(name, def string) error

SetRemoteDefaultBranch records which branch on a remote is its default.

func (*Repo) SetRemoteRef

func (r *Repo) SetRemoteRef(remoteName string, ref *RemoteRef) error

SetRemoteRef upserts a remote ref. Primary key is remote+kind+name.

func (*Repo) String

func (r *Repo) String() string

func (*Repo) TouchMirrorSync

func (r *Repo) TouchMirrorSync(lastRev string, syncEpoch int64, lastErr string) error

TouchMirrorSync updates a mirror's last sync time/rev/error.

func (*Repo) Transaction

func (r *Repo) Transaction(fn func(tx *gorm.DB) error) error

Transaction runs fn inside a database transaction, committing on success and rolling back on error or panic. This is the preferred entry point for atomic multi-table writes (BeginTx + manual Commit is easy to leak).

func (*Repo) UpdateMirrorMeta

func (r *Repo) UpdateMirrorMeta(m RepoMeta) error

UpdateMirrorMeta records mirror state (url, branch, interval, last result).

func (*Repo) UpdatePushMirrorSync

func (r *Repo) UpdatePushMirrorSync(name, lastRev, lastErr string) error

UpdatePushMirrorSync records the last pushed revision / error for a push-mirror.

func (*Repo) UpdateRemoteSyncTip

func (r *Repo) UpdateRemoteSyncTip(name, lastSyncTip string) error

UpdateRemoteSyncTip records the last successfully synced tip for a remote branch (the local revision id that mirrors the remote's tip after a pull). Empty clears it. This enables incremental/conflict-aware pulls.

func (*Repo) UpdateRepoMeta

func (r *Repo) UpdateRepoMeta(m RepoMeta) error

UpdateRepoMeta updates description/visibility/default branch.

func (*Repo) UpdateRevisionHash

func (r *Repo) UpdateRevisionHash(revisionID string, hash object.ID) error

UpdateRevisionHash atomically repoints a revision's Hash field. It preserves the existing ChangedPaths.

func (*Repo) UpdateRevisionHashCAS

func (r *Repo) UpdateRevisionHashCAS(revisionID string, expectHash, newHash object.ID) error

UpdateRevisionHashCAS repoints a revision's Hash to a new snapshot hash only if the revision still points at `expectHash`. This is an optimistic-concurrency (compare-and-swap) guard: if another writer amended the revision in between, ErrRevisionChanged is returned instead of silently last-write-wins. The snapshot is written only when the CAS succeeds.

func (*Repo) WriteObject

func (r *Repo) WriteObject(o *object.Object) error

WriteObject stores a global content-addressed object. Objects are immutable, so an existing object is never overwritten.

func (*Repo) WriteObjectsBatch

func (r *Repo) WriteObjectsBatch(objs []*object.Object) error

WriteObjectsBatch stores many objects in a single transaction, reducing round-trips when applying a bundle. Each object's id is recomputed from its content; duplicate ids are ignored (idempotent).

func (*Repo) WriteObjectsBatchTx

func (r *Repo) WriteObjectsBatchTx(tx *gorm.DB, objs []*object.Object) error

WriteObjectsBatchTx stores objects in the given transaction.

type RepoMember added in v0.9.0

type RepoMember struct {
	RepoID int64
	UserID int64
	Role   string
}

RepoMember is a user's non-owner role on a repository.

type RepoMeta

type RepoMeta struct {
	Description   string
	Visibility    string // "public" | "private"
	DefaultBranch string
	// Kind is "normal" (read-write) or "mirror" (read-only clone of an external
	// git repo; edits are forbidden).
	Kind string
	// Mirror fields are relevant only when Kind == "mirror".
	MirrorURL      string
	MirrorBranch   string
	MirrorInterval int // seconds between scheduled pulls; 0 = manual only
	MirrorLastRev  string
	MirrorLastSync int64 // epoch millis
	MirrorLastErr  string
	MirrorToken    string // never returned by API
}

RepoMeta is the hosting metadata for a repository.

type RepoMetaMap

type RepoMetaMap map[string]RepoMeta

RepoMetaMap keys a RepoMeta by "namespace/name".

type RepoRef

type RepoRef struct {
	Owner     int64
	Namespace string
	Name      string
}

RepoRef uniquely identifies a repository within the central store. Owner scopes the (namespace, name) pair: a user owns repositories only under the namespaces they own, so two users may each own an "acme/api" repo. Owner 0 means "unspecified" and is only used by internal lookups that resolve the owner from the row.

func (RepoRef) String

func (r RepoRef) String() string

type RepoStore

type RepoStore interface {
	// Object access (content-addressed, immutable, global).
	WriteObject(o *object.Object) error
	ReadObject(id object.ID) (*object.Object, error)
	ObjectExists(id object.ID) (bool, error)

	// Snapshot access.
	PutSnapshot(s *Snapshot) error
	GetSnapshot(id object.ID) (*Snapshot, error)

	// Revision access.
	PutRevision(r *Revision) error
	GetRevision(id string) (*Revision, error)
	// UpdateRevisionHash atomically points a revision's Hash to a new
	// snapshot hash.
	UpdateRevisionHash(revisionID string, hash object.ID) error
	// UpdateRevisionHashCAS repoints a revision's Hash only if it still points
	// at expectHash (optimistic concurrency; ErrRevisionChanged otherwise).
	UpdateRevisionHashCAS(revisionID string, expectHash, newHash object.ID) error
	ListRevisions() ([]*Revision, error)

	// Refs.
	PutRef(r *Ref) error
	DeleteRef(name string) error
	GetRef(name string) (*Ref, error)
	ListRefs() ([]*Ref, error)

	// Transactional writes (for atomic commit from changes).
	BeginTx() *gorm.DB
	WriteObjectsBatchTx(tx *gorm.DB, objs []*object.Object) error
	PutSnapshotTx(tx *gorm.DB, s *Snapshot) error
	PutRevisionTx(tx *gorm.DB, r *Revision) error

	// Close flushes and closes the backend.
	Close() error
}

RepoStore is the repo-scoped persistence boundary used by the semantic layer. Object primitives are content-addressed and global; the metadata methods are scoped to a single repository.

type Review

type Review struct {
	ID         int64
	MRID       int64
	ReviewerID *int64
	State      string // "approved" | "request_changes" | "comment"
	Body       string
	Created    time.Time
}

Review is a reviewer's verdict on a merge request.

type Revision

type Revision struct {
	// ID is the stable revision id (hex). Generated once and never modified.
	ID string
	// Hash points at the current snapshot's revision_hash.
	Hash object.ID
	// Created time.
	Created time.Time
	// ForkFrom records the revision id this revision was forked from, if any.
	// Used by workspace auto-fork so the origin is traceable.
	ForkFrom string
	// ChangedPaths lists the repo-relative paths whose content changed in this
	// revision relative to its parent (or all paths for the root revision). It
	// is used to cheaply answer "which revisions modified a given file" by
	// filtering the DAG walk without re-reading every tree.
	ChangedPaths []string
}

Revision is the stable, user-facing unit of work. It holds a pointer to its single current snapshot. The revision_id never changes; the pointed-to snapshot's hash does change as the revision is rewritten. Revision and Snapshot are strictly 1:1: a revision always points at one current snapshot, and rewriting replaces that snapshot entirely (old object remains in the content-addressed store if still referenced).

type Role added in v0.9.0

type Role string

Role is a user's effective role on a repository. It resolves the namespace owner to "owner"; explicit collaborator grants map to "maintainer" / "developer"; a public repository grants "developer" to everyone (including anonymous readers); otherwise the user has no role.

const (
	RoleOwner Role = "owner"
	RoleNone  Role = ""
)

Effective repository roles.

func (Role) AtLeast added in v0.9.0

func (r Role) AtLeast(min Role) bool

AtLeast reports whether r grants at least the privileges of min.

func (Role) CanMerge added in v0.9.0

func (r Role) CanMerge() bool

CanMerge reports whether the role may approve/merge change requests and manage tags (owner or maintainer).

func (Role) CanOwnSession added in v0.9.0

func (r Role) CanOwnSession() bool

CanOwnSession reports whether the role may drive repository-bound agent sessions (owner only).

func (Role) CanPropose added in v0.9.0

func (r Role) CanPropose() bool

CanPropose reports whether the role may open change requests / fork (developer and above; anonymous resolves to developer on public repos, so callers still require authentication separately for propose actions).

func (Role) CanPush added in v0.9.0

func (r Role) CanPush() bool

CanPush reports whether the role may directly push/set refs (owner only).

func (Role) CanRead added in v0.9.0

func (r Role) CanRead() bool

CanRead reports whether the role may read the repository.

type Snapshot

type Snapshot struct {
	// RevisionHash is the content-addressed id (sha) of this snapshot. It is
	// mutable: it changes whenever the revision is rewritten.
	RevisionHash object.ID
	// RevisionID is the stable identity this snapshot belongs to (never
	// changes). It is a random stable id (hex), independent of content.
	RevisionID string
	// Parents contains the ids of the parent snapshots (DAG edges).
	Parents []object.ID
	// TreeID is the root tree of this snapshot.
	TreeID object.ID
	// Description is the commit message.
	Description string
	// Author identity.
	Author Author
	// CommitTime is the creation time.
	CommitTime time.Time
}

Snapshot is the content-addressed view of a revision: it is the graph node. A Snapshot belongs to exactly one Revision (1:1), so its hash changes on rewrite (rebase) while the revision_id stays stable.

type Token

type Token struct {
	ID      int64
	Token   string
	UserID  int64
	Level   string // "read" or "write"
	Created time.Time
}

Token is a bearer token bound to a user with an access level.

type User

type User struct {
	ID          int64
	Username    string
	DisplayName string
	Disabled    bool
	// AgentTenant / AgentToken are the explicit binding to the abcp-agent
	// tenant (see the row comment in models.go).
	AgentTenant string
	AgentToken  string
	Created     time.Time
}

User is both the identity and the ownership boundary. There is no separate tenant: a user owns namespaces (and therefore repositories), holds tokens, and is bound to one abcp-agent tenant. Username is globally unique.

type WorkspaceMarker

type WorkspaceMarker struct {
	Repo            RepoRef `json:"repo"`
	CurrentRevision string  `json:"current_revision"`
	Branch          string  `json:"branch,omitempty"`
	IgnoreHash      string  `json:"ignore_hash,omitempty"`
	// Home is the central store root directory this workspace belongs to.
	// Empty means "use the process's HomeDir()".
	Home string `json:"home,omitempty"`
	// DSN optionally overrides the metadata backend location (e.g. a sqlite
	// file path or a postgres connection string). When set it takes precedence
	// over Home<DBFile>. Empty means default (Home/easyvcs.db, sqlite).
	DSN string `json:"dsn,omitempty"`
}

WorkspaceMarker is the pointer content stored at a working directory root. It records which repository (namespace/name) this checkout belongs to, which revision is currently checked out, and the location of the central store (home path and optional DSN) so a workspace is self-describing even when its store lives outside the process's EASYVCS_HOME. IgnoreHash tracks the hash of the ignore files at the last commit so a revision in .gitignore/.vcsignore can trigger history rewriting.

func LoadMarker

func LoadMarker(dir string) (string, *WorkspaceMarker, error)

LoadMarker reads and parses the workspace marker from a directory, walking upward. It returns the directory that contains the marker and the marker itself, or ErrNotFound if no marker exists above dir.

func LookupMarker

func LookupMarker(dir string) (*WorkspaceMarker, error)

LookupMarker loads a marker and returns it (without the directory). It is a convenience for callers that already know the root.

type WorkspaceRow

type WorkspaceRow struct {
	Path            string
	Repo            RepoRef
	CurrentRevision string
	Branch          string
}

WorkspaceRow is the workspaces table entry tracking a registered workspace.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL