Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions docs/import-ownership-admission.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Backup import ownership admission

Untracked imports reserve native save-path ownership before touching the
restore destination. The reservation remains held through extraction,
authoritative registration, and any returned-error recovery. Recovery does not
roll back files after registration has committed. This is not a durable
filesystem transaction or a guarantee of recovery after process or power loss.

Ordinary game creation (including peer auto-registration), primary-path updates,
and mapped-root additions/remaps cooperate with the same cross-process claim.
They wait up to 30 seconds, checking every 100 ms, before returning
`ErrPathClaimBusy`. This matches the bounded-wait policy for native topology
admission. The bound covers acquisition, not the subsequent operation. Native
ownership preparation and the SQLite commit are both inside the claim, with
filesystem resolution outside the SQLite transaction. Imports still refuse
immediately when admission is busy.

Busy is distinct from `ErrGamePathOwned`: contention does not establish an
ownership collision. Interactive registration and path-edit APIs return HTTP
409 for busy admission. Their request contexts cancel the wait before mutation;
legacy Store callers without a request context retain the bounded default.
Real ownership collisions are checked again after acquisition and still fail.

## Native lock identity

On Unix, the persistent sidecar is `<resolved-database-path>.path-claim.lock`.
It must not be unlinked on release, or later callers could lock different
inodes. Symlink and relative path spellings resolve to the same sidecar,
independently of HOME or the caller's working directory. The lock implementation
never opens/closes the SQLite file: closing a separate descriptor to that inode
can drop SQLite's process-wide POSIX locks.

Unix guarded mutations refuse databases with more than one hard link. Adjacent
sidecars cannot coordinate arbitrary hardlink spellings, and SQLite itself does
not safely support independently named journals for those aliases. This replaces
the previous hardlink admission promise with explicit refusal; it does not claim
to make opening SQLite through hardlinks safe.

Windows retains its database-file-identity named mutex and dedicated pinned
owner thread. Acquisition remains nonblocking at the native layer; ordinary
callers use the common bounded waiter. Abandoned claims fail separately from
ownership collisions and ordinary contention.

Noncooperating old binaries, external tools, concurrent alias replacement and
symlink swaps remain outside this admission contract. These claims do not
provide daemon lifecycle takeover or cross-process sync topology coordination.

## Regression coverage

- 24 simultaneous disjoint registrations across two Store handles all succeed.
- A registration resumes after an import releases its claim.
- Timeout/cancellation leave no new record and do not leak the claim.
- A waiting registration rechecks ownership after the import commits.
- The interactive handler propagates cancellation and resumes after contention.
- A child-process POSIX-lock probe remains blocked after claim release on Linux.
- Cross-process, symlink, different-cwd and different-HOME claims still exclude.
- Unix hardlinked databases fail closed; Windows mutex recursion/release tests
remain native Windows tests.
- Existing primary/named/nested import ownership and recovery regressions remain.
68 changes: 68 additions & 0 deletions internal/api/registration_claim_wait_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
package api

import (
"bytes"
"context"
"encoding/json"
"errors"
"net/http"
"net/http/httptest"
"path/filepath"
"testing"
"time"

"github.com/opensave/opensave/internal/store"
)

// Exercise the interactive handler through daemon registration, not just the
// Store waiter: cancellation must not become a delayed successful mutation.
func TestRegistrationClaimHandlerWaitAndCancellation(t *testing.T) {
for _, cancelled := range []bool{false, true} {
name := "drains"
if cancelled {
name = "cancelled"
}
t.Run(name, func(t *testing.T) {
ts := startTestServer(t)
a, err := ts.daemon.Store.BeginImportPath(filepath.Join(t.TempDir(), "import"), "incoming")
if err != nil {
t.Fatal(err)
}
defer a.Release()
body, _ := json.Marshal(map[string]string{"name": "Claim Wait", "savePath": ts.saveDir})
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
req := httptest.NewRequest(http.MethodPost, "/api/games", bytes.NewReader(body)).WithContext(ctx)
response := httptest.NewRecorder()
done := make(chan struct{})
go func() { ts.server.handleTrackGame(response, req); close(done) }()
select {
case <-done:
t.Fatalf("handler refused without waiting: %d %s", response.Code, response.Body)
case <-time.After(60 * time.Millisecond):
}
if cancelled {
cancel()
} else {
a.Release()
}
select {
case <-done:
case <-time.After(2 * time.Second):
t.Fatal("handler did not finish")
}
a.Release()
_, err = ts.daemon.Store.FindGameBySavePath(ts.saveDir)
if cancelled {
if !errors.Is(err, store.ErrNotFound) {
t.Fatalf("cancelled request registered game: %v", err)
}
if response.Code != http.StatusConflict {
t.Fatalf("busy cancellation HTTP %d: %s", response.Code, response.Body)
}
} else if err != nil || response.Code != http.StatusOK {
t.Fatalf("drained request HTTP %d, game error %v: %s", response.Code, err, response.Body)
}
})
}
}
8 changes: 4 additions & 4 deletions internal/api/routes.go
Original file line number Diff line number Diff line change
Expand Up @@ -374,12 +374,12 @@ func (s *Server) handleTrackGame(w http.ResponseWriter, r *http.Request) {
return
}

game, err := s.Daemon.TrackGame(store.Game{Name: body.Name, SavePath: body.SavePath, AppID: body.AppID, ExePath: body.ExePath})
game, err := s.Daemon.TrackGameContext(r.Context(), store.Game{Name: body.Name, SavePath: body.SavePath, AppID: body.AppID, ExePath: body.ExePath})
if err != nil {
// Duplicates (id or path) are conflicts; anything else the daemon
// rejects is bad input.
status := http.StatusBadRequest
if errors.Is(err, store.ErrGamePathOwned) || errors.Is(err, store.ErrOwnershipClaimsChanged) ||
if errors.Is(err, store.ErrGamePathOwned) || errors.Is(err, store.ErrPathClaimBusy) || errors.Is(err, store.ErrOwnershipClaimsChanged) ||
strings.Contains(err.Error(), "already track") ||
strings.Contains(err.Error(), "already exists") {
status = http.StatusConflict
Expand Down Expand Up @@ -489,9 +489,9 @@ func (s *Server) handleUpdateGame(w http.ResponseWriter, r *http.Request) {
game.LastManifestHash = s.Daemon.LastSnapshotHashUnder(game, oldIgnore)
}

if err := s.Daemon.Store.UpdateGame(game); err != nil {
if err := s.Daemon.Store.UpdateGameContext(r.Context(), game); err != nil {
status := notFoundToStatus(err)
if errors.Is(err, store.ErrOwnershipClaimsChanged) || errors.Is(err, store.ErrGamePathOwned) {
if errors.Is(err, store.ErrPathClaimBusy) || errors.Is(err, store.ErrOwnershipClaimsChanged) || errors.Is(err, store.ErrGamePathOwned) {
status = http.StatusConflict
}
writeError(w, status, err.Error())
Expand Down
4 changes: 2 additions & 2 deletions internal/api/routes_roots.go
Original file line number Diff line number Diff line change
Expand Up @@ -75,9 +75,9 @@ func (s *Server) handleAddGameRoot(w http.ResponseWriter, r *http.Request) {
// to hear about rather than a server fault: "that folder is already
// covered by the main save" is a sentence, not a 500.
oldRoots, _ := s.Daemon.Store.GameRootPaths(gameID)
if err := s.Daemon.Store.AddGameRoot(gameID, body.Name, path); err != nil {
if err := s.Daemon.Store.AddGameRootContext(r.Context(), gameID, body.Name, path); err != nil {
status := http.StatusBadRequest
if errors.Is(err, store.ErrOwnershipClaimsChanged) || errors.Is(err, store.ErrGamePathOwned) {
if errors.Is(err, store.ErrPathClaimBusy) || errors.Is(err, store.ErrOwnershipClaimsChanged) || errors.Is(err, store.ErrGamePathOwned) {
status = http.StatusConflict
}
writeError(w, status, err.Error())
Expand Down
14 changes: 10 additions & 4 deletions internal/daemon/daemon.go
Original file line number Diff line number Diff line change
Expand Up @@ -802,7 +802,13 @@ func isDuplicateGameID(err error) bool {
// TrackGame adds a new game, takes its initial snapshot (when the save
// location already has content), and starts watching it.
func (d *Daemon) TrackGame(game store.Game) (store.Game, error) {
return d.trackGameAdmitted(game, nil)
return d.TrackGameContext(context.Background(), game)
}

// TrackGameContext allows an abandoned interactive request to cancel while
// waiting for another process's save-path claim.
func (d *Daemon) TrackGameContext(ctx context.Context, game store.Game) (store.Game, error) {
return d.trackGameAdmitted(ctx, game, nil)
}

// TrackImportedGame reuses native tracking while retaining the cross-process
Expand All @@ -811,10 +817,10 @@ func (d *Daemon) TrackImportedGame(game store.Game, admission *store.ImportPathA
if admission == nil {
return store.Game{}, fmt.Errorf("missing import admission")
}
return d.trackGameAdmitted(game, admission)
return d.trackGameAdmitted(context.Background(), game, admission)
}

func (d *Daemon) trackGameAdmitted(game store.Game, admission *store.ImportPathAdmission) (store.Game, error) {
func (d *Daemon) trackGameAdmitted(ctx context.Context, game store.Game, admission *store.ImportPathAdmission) (store.Game, error) {
abs, err := d.ValidateSavePath(game.SavePath)
if err != nil {
return store.Game{}, err
Expand Down Expand Up @@ -894,7 +900,7 @@ func (d *Daemon) trackGameAdmitted(game store.Game, admission *store.ImportPathA
if admission != nil {
createErr = d.Store.CreateGameAdmitted(game, admission)
} else {
createErr = d.Store.CreateGame(game)
createErr = d.Store.CreateGameContext(ctx, game)
}
if err := createErr; err != nil {
// The id was free a moment ago. If it is taken now, a paired device
Expand Down
6 changes: 4 additions & 2 deletions internal/store/db.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import (
"runtime"
"sort"
"strings"
"time"

"github.com/jmoiron/sqlx"
_ "modernc.org/sqlite"
Expand All @@ -23,8 +24,9 @@ var migrationsFS embed.FS
// methods (see settings.go, games.go, branches.go, snapshots.go, peers.go,
// cloudtokens.go).
type Store struct {
db *sqlx.DB
path string // the database file, for EnableIncrementalVacuum's space check
db *sqlx.DB
claimWaitFor time.Duration // test-injectable admission bound; defaults to 30s
path string // the database file, for EnableIncrementalVacuum's space check
}

// Open creates (if needed) and opens the SQLite database at path, applying
Expand Down
8 changes: 7 additions & 1 deletion internal/store/game_roots.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package store

import (
"context"
"database/sql"
"errors"
"fmt"
Expand Down Expand Up @@ -152,7 +153,12 @@ func isAbsoluteAnyOS(p string) bool {
// A path that overlaps the game's primary location or another of its
// locations is refused; see overlaps.
func (s *Store) AddGameRoot(gameID, name, path string) error {
done, err := s.claimLock()
return s.AddGameRootContext(context.Background(), gameID, name, path)
}

// AddGameRootContext stops waiting for ownership admission when the caller cancels.
func (s *Store) AddGameRootContext(ctx context.Context, gameID, name, path string) error {
done, err := s.claimLockContext(ctx)
if err != nil {
return err
}
Expand Down
15 changes: 13 additions & 2 deletions internal/store/games.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package store

import (
"context"
"database/sql"
"errors"
"fmt"
Expand Down Expand Up @@ -82,7 +83,12 @@ type Game struct {
// CreateGame inserts a new game and its default "main" branch in one
// transaction.
func (s *Store) CreateGame(g Game) error {
done, err := s.claimLock()
return s.CreateGameContext(context.Background(), g)
}

// CreateGameContext stops waiting for ownership admission when the caller cancels.
func (s *Store) CreateGameContext(ctx context.Context, g Game) error {
done, err := s.claimLockContext(ctx)
if err != nil {
return err
}
Expand Down Expand Up @@ -171,7 +177,12 @@ func (s *Store) ListGames() ([]Game, error) {
// update — id, save_path are updatable too since the UI allows relocating
// a tracked save folder).
func (s *Store) UpdateGame(g Game) error {
done, err := s.claimLock()
return s.UpdateGameContext(context.Background(), g)
}

// UpdateGameContext stops waiting for ownership admission when the caller cancels.
func (s *Store) UpdateGameContext(ctx context.Context, g Game) error {
done, err := s.claimLockContext(ctx)
if err != nil {
return err
}
Expand Down
61 changes: 57 additions & 4 deletions internal/store/import_admission.go
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
package store

import (
"context"
"errors"
"fmt"
"path/filepath"
"time"
)

// ImportPathAdmission owns the native cross-process path claim throughout
Expand All @@ -14,10 +17,60 @@ type ImportPathAdmission struct {
release func()
}

// claimLock protects native registrations of primary/named save roots and
// untracked backup extraction. The lock is the database file itself, so a
// different HOME, cwd, or hardlink spelling still contends.
// ErrPathClaimBusy means admission timed out or another import holds the
// claim. It is not evidence that any save location overlaps another game.
var ErrPathClaimBusy = errors.New("save-location changes are busy; try again in a moment")

const pathClaimWait = 30 * time.Second
const pathClaimPoll = 100 * time.Millisecond

// Ordinary registrations wait for short-lived work, just as native topology
// edits do. The claim covers preparation AND commit, without holding a SQLite
// transaction while waiting or resolving filesystem paths.
func (s *Store) claimLock() (func(), error) {
return s.claimLockContext(context.Background())
}

func (s *Store) claimLockContext(parent context.Context) (func(), error) {
limit := s.claimWaitFor
if limit <= 0 {
limit = pathClaimWait
}
ctx, cancel := context.WithTimeout(parent, limit)
defer cancel()
return s.waitClaimLock(ctx)
}

func (s *Store) waitClaimLock(ctx context.Context) (func(), error) {
for {
if err := ctx.Err(); err != nil {
return nil, fmt.Errorf("%w: %w", ErrPathClaimBusy, err)
}
release, err := s.tryClaimLock()
if err == nil {
// Cancellation racing acquisition must not admit a new mutation.
if err := ctx.Err(); err != nil {
release()
return nil, fmt.Errorf("%w: %w", ErrPathClaimBusy, err)
}
return release, nil
}
if !errors.Is(err, ErrPathClaimBusy) {
return nil, err
}
timer := time.NewTimer(pathClaimPoll)
select {
case <-ctx.Done():
timer.Stop()
return nil, fmt.Errorf("%w: %w", ErrPathClaimBusy, ctx.Err())
case <-timer.C:
}
}
}

// Imports retain immediate refusal. Resolving symlinks makes aliases share the
// same sidecar on Unix; HOME and cwd never determine the lock location.
func (s *Store) tryClaimLock() (func(), error) {
canonical, err := filepath.Abs(s.path)
if err != nil {
return nil, err
Expand All @@ -36,7 +89,7 @@ func (s *Store) claimLock() (func(), error) {
// BeginImportPath reserves ownership through every filesystem effect and the
// eventual game registration. A read failure always refuses admission.
func (s *Store) BeginImportPath(path, incomingGameID string) (*ImportPathAdmission, error) {
release, err := s.claimLock()
release, err := s.tryClaimLock()
if err != nil {
return nil, err
}
Expand Down
Loading
Loading