security/hakurei
security/hakurei
5
2
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases 7 Wiki Activity

internal/store: export new interface
All checks were successful
Test / Create distribution (push) Successful in 33s
Details
Test / Sandbox (push) Successful in 2m19s
Details
Test / Hakurei (push) Successful in 3m13s
Details
Test / Hpkg (push) Successful in 4m4s
Details
Test / Sandbox (race detector) (push) Successful in 4m16s
Details
Test / Hakurei (race detector) (push) Successful in 4m58s
Details
Test / Flake checks (push) Successful in 1m30s
Details

Browse Source 
This exposes store operations safe for direct access, and enables #19 to be implemented in internal/outcome.

Signed-off-by: Ophestra <cat@gensokyo.uk>
This commit is contained in:
Ophestra 2025-10-31 03:41:26 +09:00
parent b25ade5f3d
commit b667fea1cb
Signed by: cat
SSH Key Fingerprint: SHA256:gQ67O0enBZ7UdZypgtspB2FDM1g3GVw8nX0XSdcFw8Q
5 changed files with 225 additions and 191 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
internal/store/compat.go
View File

@ -3,7 +3,6 @@ package store
import (
"errors"
"maps"
"strconv"
"hakurei.app/container/check"
"hakurei.app/hst"
@ -23,29 +22,29 @@ type Compat interface {
List() (identities []int, err error)
}
func (s *stateStore) Do(identity int, f func(c Cursor)) (bool, error) {
if h, err := s.identityHandle(identity); err != nil {
func (s *Store) Do(identity int, f func(c Cursor)) (bool, error) {
if h, err := s.Handle(identity); err != nil {
return false, err
} else {
return h.do(f)
}
}
// storeAdapter satisfies [Store] via stateStore.
// storeAdapter satisfies [Compat] via [Store].
type storeAdapter struct {
msg message.Msg
*stateStore
*Store
}
func (s storeAdapter) List() ([]int, error) {
segments, n, err := s.segments()
segments, n, err := s.Segments()
if err != nil {
return nil, err
}
identities := make([]int, 0, n)
for si := range segments {
if si.err != nil {
if si.Err != nil {
if m, ok := message.GetMessage(err); ok {
s.msg.Verbose(m)
} else {
@ -54,14 +53,14 @@ func (s storeAdapter) List() ([]int, error) {
}
continue
}
identities = append(identities, si.identity)
identities = append(identities, si.Identity)
}
return identities, nil
}
// NewMulti returns an instance of the multi-file store.
func NewMulti(msg message.Msg, prefix *check.Absolute) Compat {
return storeAdapter{msg, newStore(prefix.Append("state"))}
return storeAdapter{msg, New(prefix.Append("state"))}
}
// Cursor provides access to the store of an identity.
@ -72,10 +71,10 @@ type Cursor interface {
Len() (int, error)
}
// do implements stateStore.Do on storeHandle.
func (h *storeHandle) do(f func(c Cursor)) (bool, error) {
if unlock, err := h.fileMu.Lock(); err != nil {
return false, &hst.AppError{Step: "acquire lock on store segment " + strconv.Itoa(h.identity), Err: err}
// do implements [Compat.Do] on [Handle].
func (h *Handle) do(f func(c Cursor)) (bool, error) {
if unlock, err := h.Lock(); err != nil {
return false, err
} else {
defer unlock()
}
@ -86,28 +85,28 @@ func (h *storeHandle) do(f func(c Cursor)) (bool, error) {
/* these compatibility methods must only be called while fileMu is held */
func (h *storeHandle) Save(state *hst.State) error {
return (&stateEntryHandle{nil, h.path.Append(state.ID.String()), state.ID}).save(state)
func (h *Handle) Save(state *hst.State) error {
return (&EntryHandle{nil, h.Path.Append(state.ID.String()), state.ID}).Save(state)
}
func (h *storeHandle) Destroy(id hst.ID) error {
return (&stateEntryHandle{nil, h.path.Append(id.String()), id}).destroy()
func (h *Handle) Destroy(id hst.ID) error {
return (&EntryHandle{nil, h.Path.Append(id.String()), id}).Destroy()
}
func (h *storeHandle) Load() (map[hst.ID]*hst.State, error) {
entries, n, err := h.entries()
func (h *Handle) Load() (map[hst.ID]*hst.State, error) {
entries, n, err := h.Entries()
if err != nil {
return nil, err
}
r := make(map[hst.ID]*hst.State, n)
for eh := range entries {
if eh.decodeErr != nil {
err = eh.decodeErr
if eh.DecodeErr != nil {
err = eh.DecodeErr
break
}
var s hst.State
if _, err = eh.load(&s); err != nil {
if _, err = eh.Load(&s); err != nil {
break
}
r[eh.ID] = &s
@ -115,16 +114,16 @@ func (h *storeHandle) Load() (map[hst.ID]*hst.State, error) {
return r, err
}
func (h *storeHandle) Len() (int, error) {
entries, _, err := h.entries()
func (h *Handle) Len() (int, error) {
entries, _, err := h.Entries()
if err != nil {
return -1, err
}
var n int
for eh := range entries {
if eh.decodeErr != nil {
err = eh.decodeErr
if eh.DecodeErr != nil {
err = eh.DecodeErr
}
n++
}

106
internal/store/segment.go
View File

@ -13,49 +13,52 @@ import (
"hakurei.app/internal/lockedfile"
)
// stateEntryHandle is a handle on a state entry retrieved from a storeHandle.
// Must only be used while its parent storeHandle.fileMu is held.
type stateEntryHandle struct {
// EntryHandle is a handle on a state entry retrieved from a [Handle].
// Must only be used while its parent [Handle.Lock] is held.
type EntryHandle struct {
// Error returned while decoding pathname.
// A non-nil value disables stateEntryHandle.
decodeErr error
// A non-nil value disables EntryHandle.
DecodeErr error
// Checked path to entry file.
pathname *check.Absolute
// Checked pathname to entry file.
Pathname *check.Absolute
hst.ID
}
// open opens the underlying state entry file, returning [hst.AppError] for a non-nil error.
func (eh *stateEntryHandle) open(flag int, perm os.FileMode) (*os.File, error) {
if eh.decodeErr != nil {
return nil, eh.decodeErr
// open opens the underlying state entry file.
// A non-nil error returned by open is of type [hst.AppError].
func (eh *EntryHandle) open(flag int, perm os.FileMode) (*os.File, error) {
if eh.DecodeErr != nil {
return nil, eh.DecodeErr
}
if f, err := os.OpenFile(eh.pathname.String(), flag, perm); err != nil {
if f, err := os.OpenFile(eh.Pathname.String(), flag, perm); err != nil {
return nil, &hst.AppError{Step: "open state entry", Err: err}
} else {
return f, nil
}
}
// destroy removes the underlying state entry file, returning [hst.AppError] for a non-nil error.
func (eh *stateEntryHandle) destroy() error {
// Destroy removes the underlying state entry.
// A non-nil error returned by Destroy is of type [hst.AppError].
func (eh *EntryHandle) Destroy() error {
// destroy does not go through open
if eh.decodeErr != nil {
return eh.decodeErr
if eh.DecodeErr != nil {
return eh.DecodeErr
}
if err := os.Remove(eh.pathname.String()); err != nil {
if err := os.Remove(eh.Pathname.String()); err != nil {
return &hst.AppError{Step: "destroy state entry", Err: err}
}
return nil
}
// save encodes [hst.State] and writes it to the underlying file.
// Save encodes [hst.State] and writes it to the underlying file.
// An error is returned if a file already exists with the same identifier.
// save does not validate the embedded [hst.Config].
func (eh *stateEntryHandle) save(state *hst.State) error {
// Save does not validate the embedded [hst.Config].
// A non-nil error returned by Save is of type [hst.AppError].
func (eh *EntryHandle) Save(state *hst.State) error {
f, err := eh.open(os.O_RDWR|os.O_CREATE|os.O_EXCL, 0600)
if err != nil {
return err
@ -68,10 +71,11 @@ func (eh *stateEntryHandle) save(state *hst.State) error {
return err
}
// load loads and validates the state entry header, and returns the [hst.Enablement] byte.
// Load loads and validates the state entry header, and returns the [hst.Enablement] byte.
// for a non-nil v, the full state payload is decoded and stored in the value pointed to by v.
// load validates the embedded hst.Config value.
func (eh *stateEntryHandle) load(v *hst.State) (hst.Enablement, error) {
// Load validates the embedded [hst.Config] value.
// A non-nil error returned by Load is of type [hst.AppError].
func (eh *EntryHandle) Load(v *hst.State) (hst.Enablement, error) {
f, err := eh.open(os.O_RDONLY, 0)
if err != nil {
return 0, err
@ -94,31 +98,42 @@ func (eh *stateEntryHandle) load(v *hst.State) (hst.Enablement, error) {
return et, err
}
// storeHandle is a handle on a stateStore segment.
// Initialised by stateStore.identityHandle.
type storeHandle struct {
// Handle is a handle on a [Store] segment.
// Initialised by [Store.Handle].
type Handle struct {
// Identity of instances tracked by this segment.
identity int
// Pathname of directory that the segment referred to by storeHandle is rooted in.
path *check.Absolute
// Inter-process mutex to synchronise operations against resources in this segment.
fileMu *lockedfile.Mutex
Identity int
// Pathname of directory that the segment referred to by Handle is rooted in.
Path *check.Absolute
// Inter-process mutex to synchronise operations against resources in this segment.
// Must not be held directly, callers should use [Handle.Lock] instead.
fileMu *lockedfile.Mutex
// Must be held alongside fileMu.
mu sync.Mutex
}
// entries returns an iterator over all stateEntryHandle held in this segment.
// Must be called while holding a lock on mu and fileMu.
// A non-nil error attached to a stateEntryHandle indicates a malformed identifier and is of type [hst.AppError].
// A non-nil error returned by entries is of type [hst.AppError].
func (h *storeHandle) entries() (iter.Seq[*stateEntryHandle], int, error) {
// Lock attempts to acquire a lock on [Handle].
// If successful, Lock returns a non-nil unlock function.
// A non-nil error returned by Lock is of type [hst.AppError].
func (h *Handle) Lock() (unlock func(), err error) {
if unlock, err = h.fileMu.Lock(); err != nil {
return nil, &hst.AppError{Step: "acquire lock on store segment " + strconv.Itoa(h.Identity), Err: err}
}
return
}
// Entries returns an iterator over all [EntryHandle] held in this segment.
// Must be called while holding [Handle.Lock].
// A non-nil error attached to a [EntryHandle] indicates a malformed identifier and is of type [hst.AppError].
// A non-nil error returned by Entries is of type [hst.AppError].
func (h *Handle) Entries() (iter.Seq[*EntryHandle], int, error) {
// for error reporting
const step = "read store segment entries"
// read directory contents, should only contain storeMutexName and identifier
var entries []os.DirEntry
if pl, err := os.ReadDir(h.path.String()); err != nil {
if pl, err := os.ReadDir(h.Path.String()); err != nil {
return nil, -1, &hst.AppError{Step: step, Err: err}
} else {
entries = pl
@ -130,25 +145,25 @@ func (h *storeHandle) entries() (iter.Seq[*stateEntryHandle], int, error) {
l--
}
return func(yield func(*stateEntryHandle) bool) {
return func(yield func(*EntryHandle) bool) {
for _, ent := range entries {
var eh = stateEntryHandle{pathname: h.path.Append(ent.Name())}
var eh = EntryHandle{Pathname: h.Path.Append(ent.Name())}
// this should never happen
if ent.IsDir() {
eh.decodeErr = &hst.AppError{Step: step,
eh.DecodeErr = &hst.AppError{Step: step,
Err: errors.New("unexpected directory " + strconv.Quote(ent.Name()) + " in store")}
goto out
}
// silently skip lock file
if ent.Name() == storeMutexName {
if ent.Name() == MutexName {
continue
}
// this either indicates a serious bug or external interference
if err := eh.ID.UnmarshalText([]byte(ent.Name())); err != nil {
eh.decodeErr = &hst.AppError{Step: "decode store segment entry", Err: err}
eh.DecodeErr = &hst.AppError{Step: "decode store segment entry", Err: err}
goto out
}
@ -159,3 +174,10 @@ func (h *storeHandle) entries() (iter.Seq[*stateEntryHandle], int, error) {
}
}, l, nil
}
// newHandle returns the address of a new segment [Handle] rooted in base.
func newHandle(base *check.Absolute, identity int) *Handle {
h := Handle{Identity: identity, Path: base.Append(strconv.Itoa(identity))}
h.fileMu = lockedfile.MutexAt(h.Path.Append(MutexName).String())
return &h
}

107
internal/store/segment_test.go
View File

@ -1,7 +1,8 @@
package store
package store_test
import (
"errors"
"io"
"iter"
"os"
"reflect"
@ -9,31 +10,44 @@ import (
"strings"
"syscall"
"testing"
_ "unsafe"
"hakurei.app/container/check"
"hakurei.app/container/stub"
"hakurei.app/hst"
"hakurei.app/internal/lockedfile"
"hakurei.app/internal/store"
)
//go:linkname newTemplateState hakurei.app/internal/store.newTemplateState
func newTemplateState() *hst.State
//go:linkname entryDecode hakurei.app/internal/store.entryDecode
func entryDecode(r io.Reader, p *hst.State) (hst.Enablement, error)
//go:linkname newHandle hakurei.app/internal/store.newHandle
func newHandle(base *check.Absolute, identity int) *store.Handle
//go:linkname open hakurei.app/internal/store.(*EntryHandle).open
func open(eh *store.EntryHandle, flag int, perm os.FileMode) (*os.File, error)
func TestStateEntryHandle(t *testing.T) {
t.Parallel()
t.Run("lockout", func(t *testing.T) {
t.Parallel()
wantErr := func() error { return stub.UniqueError(0) }
eh := stateEntryHandle{decodeErr: wantErr(), pathname: check.MustAbs("/proc/nonexistent")}
eh := store.EntryHandle{DecodeErr: wantErr(), Pathname: check.MustAbs("/proc/nonexistent")}
if _, err := eh.open(-1, 0); !reflect.DeepEqual(err, wantErr()) {
if _, err := open(&eh, -1, 0); !reflect.DeepEqual(err, wantErr()) {
t.Errorf("open: error = %v, want %v", err, wantErr())
}
if err := eh.destroy(); !reflect.DeepEqual(err, wantErr()) {
if err := eh.Destroy(); !reflect.DeepEqual(err, wantErr()) {
t.Errorf("destroy: error = %v, want %v", err, wantErr())
}
if err := eh.save(nil); !reflect.DeepEqual(err, wantErr()) {
if err := eh.Save(nil); !reflect.DeepEqual(err, wantErr()) {
t.Errorf("save: error = %v, want %v", err, wantErr())
}
if _, err := eh.load(nil); !reflect.DeepEqual(err, wantErr()) {
if _, err := eh.Load(nil); !reflect.DeepEqual(err, wantErr()) {
t.Errorf("load: error = %v, want %v", err, wantErr())
}
})
@ -42,30 +56,30 @@ func TestStateEntryHandle(t *testing.T) {
t.Parallel()
{
eh := stateEntryHandle{pathname: check.MustAbs(t.TempDir()).Append("entry")}
if f, err := eh.open(os.O_CREATE|syscall.O_EXCL, 0); err != nil {
eh := store.EntryHandle{Pathname: check.MustAbs(t.TempDir()).Append("entry")}
if f, err := open(&eh, os.O_CREATE|syscall.O_EXCL, 0); err != nil {
t.Fatalf("open: error = %v", err)
} else if err = f.Close(); err != nil {
t.Errorf("Close: error = %v", err)
}
if err := eh.destroy(); err != nil {
if err := eh.Destroy(); err != nil {
t.Fatalf("destroy: error = %v", err)
}
}
t.Run("nonexistent", func(t *testing.T) {
t.Parallel()
eh := stateEntryHandle{pathname: check.MustAbs("/proc/nonexistent")}
eh := store.EntryHandle{Pathname: check.MustAbs("/proc/nonexistent")}
wantErrOpen := &hst.AppError{Step: "open state entry",
Err: &os.PathError{Op: "open", Path: "/proc/nonexistent", Err: syscall.ENOENT}}
if _, err := eh.open(os.O_CREATE|syscall.O_EXCL, 0); !reflect.DeepEqual(err, wantErrOpen) {
if _, err := open(&eh, os.O_CREATE|syscall.O_EXCL, 0); !reflect.DeepEqual(err, wantErrOpen) {
t.Errorf("open: error = %#v, want %#v", err, wantErrOpen)
}
wantErrDestroy := &hst.AppError{Step: "destroy state entry",
Err: &os.PathError{Op: "remove", Path: "/proc/nonexistent", Err: syscall.ENOENT}}
if err := eh.destroy(); !reflect.DeepEqual(err, wantErrDestroy) {
if err := eh.Destroy(); !reflect.DeepEqual(err, wantErrDestroy) {
t.Errorf("destroy: error = %#v, want %#v", err, wantErrDestroy)
}
})
@ -73,10 +87,10 @@ func TestStateEntryHandle(t *testing.T) {
t.Run("saveload", func(t *testing.T) {
t.Parallel()
eh := stateEntryHandle{pathname: check.MustAbs(t.TempDir()).Append("entry"),
eh := store.EntryHandle{Pathname: check.MustAbs(t.TempDir()).Append("entry"),
ID: newTemplateState().ID}
if err := eh.save(newTemplateState()); err != nil {
if err := eh.Save(newTemplateState()); err != nil {
t.Fatalf("save: error = %v", err)
}
@ -87,7 +101,7 @@ func TestStateEntryHandle(t *testing.T) {
t.Parallel()
var got hst.State
if f, err := os.Open(eh.pathname.String()); err != nil {
if f, err := os.Open(eh.Pathname.String()); err != nil {
t.Fatal(err.Error())
} else if _, err = entryDecode(f, &got); err != nil {
t.Fatalf("entryDecode: error = %v", err)
@ -103,7 +117,7 @@ func TestStateEntryHandle(t *testing.T) {
t.Run("load header only", func(t *testing.T) {
t.Parallel()
if et, err := eh.load(nil); err != nil {
if et, err := eh.Load(nil); err != nil {
t.Fatalf("load: error = %v", err)
} else if want := newTemplateState().Enablements.Unwrap(); et != want {
t.Errorf("load: et = %x, want %x", et, want)
@ -114,7 +128,7 @@ func TestStateEntryHandle(t *testing.T) {
t.Parallel()
var got hst.State
if _, err := eh.load(&got); err != nil {
if _, err := eh.Load(&got); err != nil {
t.Fatalf("load: error = %v", err)
} else if want := newTemplateState(); !reflect.DeepEqual(&got, want) {
t.Errorf("load: %#v, want %#v", &got, want)
@ -126,8 +140,8 @@ func TestStateEntryHandle(t *testing.T) {
wantErr := &hst.AppError{Step: "validate state identifier", Err: os.ErrInvalid,
Msg: "state entry 00000000000000000000000000000000 has unexpected id aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
ehi := stateEntryHandle{pathname: eh.pathname}
if _, err := ehi.load(new(hst.State)); !reflect.DeepEqual(err, wantErr) {
ehi := store.EntryHandle{Pathname: eh.Pathname}
if _, err := ehi.Load(new(hst.State)); !reflect.DeepEqual(err, wantErr) {
t.Errorf("load: error = %#v, want %#v", err, wantErr)
}
})
@ -141,8 +155,8 @@ func TestStoreHandle(t *testing.T) {
testCases := []struct {
name string
ents [2][]string
want func(newEh func(err error, name string) *stateEntryHandle) []*stateEntryHandle
ext func(t *testing.T, entries iter.Seq[*stateEntryHandle], n int)
want func(newEh func(err error, name string) *store.EntryHandle) []*store.EntryHandle
ext func(t *testing.T, entries iter.Seq[*store.EntryHandle], n int)
}{
{"errors", [2][]string{{
"e81eb203b4190ac5c3842ef44d429945",
@ -150,8 +164,8 @@ func TestStoreHandle(t *testing.T) {
"f0-invalid",
}, {
"f1-directory",
}}, func(newEh func(err error, name string) *stateEntryHandle) []*stateEntryHandle {
return []*stateEntryHandle{
}}, func(newEh func(err error, name string) *store.EntryHandle) []*store.EntryHandle {
return []*store.EntryHandle{
newEh(nil, "e81eb203b4190ac5c3842ef44d429945"),
newEh(&hst.AppError{Step: "decode store segment entry",
Err: hst.IdentifierDecodeError{Err: hst.ErrIdentifierLength}}, "f0-invalid"),
@ -167,17 +181,17 @@ func TestStoreHandle(t *testing.T) {
"c8c8e2c4aea5c32fe47240ff8caa874e",
"fa0d30b249d80f155a1f80ceddcc32f2",
"lock",
}}, func(newEh func(err error, name string) *stateEntryHandle) []*stateEntryHandle {
return []*stateEntryHandle{
}}, func(newEh func(err error, name string) *store.EntryHandle) []*store.EntryHandle {
return []*store.EntryHandle{
newEh(nil, "7958cfbb9272d9cf9cfd61c85afa13f1"),
newEh(nil, "c8c8e2c4aea5c32fe47240ff8caa874e"),
newEh(nil, "d0b5f7446dd5bd3424ff2f7ac9cace1e"),
newEh(nil, "e81eb203b4190ac5c3842ef44d429945"),
newEh(nil, "fa0d30b249d80f155a1f80ceddcc32f2"),
}
}, func(t *testing.T, entries iter.Seq[*stateEntryHandle], n int) {
}, func(t *testing.T, entries iter.Seq[*store.EntryHandle], n int) {
if n != 5 {
t.Fatalf("entries: n = %d", n)
t.Fatalf("Entries: n = %d", n)
}
// check partial drain
@ -190,29 +204,26 @@ func TestStoreHandle(t *testing.T) {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
p := check.MustAbs(t.TempDir()).Append("segment")
if err := os.Mkdir(p.String(), 0700); err != nil {
base := check.MustAbs(t.TempDir()).Append("store")
segment := base.Append("9")
if err := os.MkdirAll(segment.String(), 0700); err != nil {
t.Fatal(err.Error())
}
createEntries(t, p, tc.ents)
createEntries(t, segment, tc.ents)
var got []*stateEntryHandle
if entries, n, err := (&storeHandle{
identity: -0xbad,
path: p,
fileMu: lockedfile.MutexAt(p.Append("lock").String()),
}).entries(); err != nil {
t.Fatalf("entries: error = %v", err)
var got []*store.EntryHandle
if entries, n, err := newHandle(base, 9).Entries(); err != nil {
t.Fatalf("Entries: error = %v", err)
} else {
got = slices.AppendSeq(make([]*stateEntryHandle, 0, n), entries)
got = slices.AppendSeq(make([]*store.EntryHandle, 0, n), entries)
if tc.ext != nil {
tc.ext(t, entries, n)
}
}
slices.SortFunc(got, func(a, b *stateEntryHandle) int { return strings.Compare(a.pathname.String(), b.pathname.String()) })
want := tc.want(func(err error, name string) *stateEntryHandle {
eh := stateEntryHandle{decodeErr: err, pathname: p.Append(name)}
slices.SortFunc(got, func(a, b *store.EntryHandle) int { return strings.Compare(a.Pathname.String(), b.Pathname.String()) })
want := tc.want(func(err error, name string) *store.EntryHandle {
eh := store.EntryHandle{DecodeErr: err, Pathname: segment.Append(name)}
if err == nil {
if err = eh.UnmarshalText([]byte(name)); err != nil {
t.Fatalf("UnmarshalText: error = %v", err)
@ -222,7 +233,7 @@ func TestStoreHandle(t *testing.T) {
})
if !reflect.DeepEqual(got, want) {
t.Errorf("entries: %q, want %q", got, want)
t.Errorf("Entries: %q, want %q", got, want)
}
})
}
@ -233,11 +244,11 @@ func TestStoreHandle(t *testing.T) {
Path: "/proc/nonexistent",
Err: syscall.ENOENT,
}}
if _, _, err := (&storeHandle{
identity: -0xbad,
path: check.MustAbs("/proc/nonexistent"),
}).entries(); !reflect.DeepEqual(err, wantErr) {
t.Fatalf("entries: error = %#v, want %#v", err, wantErr)
if _, _, err := (&store.Handle{
Identity: -0xbad,
Path: check.MustAbs("/proc/nonexistent"),
}).Entries(); !reflect.DeepEqual(err, wantErr) {
t.Fatalf("Entries: error = %#v, want %#v", err, wantErr)
}
})
}

69
internal/store/store.go
View File

@ -1,3 +1,4 @@
// Package store implements cross-process state tracking for hakurei container instances.
package store
import (
@ -14,16 +15,16 @@ import (
"hakurei.app/internal/lockedfile"
)
// storeMutexName is the pathname of the file backing [lockedfile.Mutex] of a stateStore and storeHandle.
const storeMutexName = "lock"
// MutexName is the pathname of the file backing [lockedfile.Mutex] of a [Store] and [Handle].
const MutexName = "lock"
// A stateStore keeps track of [hst.State] via a well-known filesystem accessible to all hakurei priv-side processes.
// Access to store data and related resources are synchronised on a per-segment basis via storeHandle.
type stateStore struct {
// A Store keeps track of [hst.State] via a well-known filesystem accessible to all hakurei priv-side processes.
// Access to store data and related resources are synchronised on a per-segment basis via [Handle].
type Store struct {
// Pathname of directory that the store is rooted in.
base *check.Absolute
// All currently known instances of storeHandle, keyed by their identity.
// All currently known instances of Handle, keyed by their identity.
handles sync.Map
// Inter-process mutex to synchronise operations against the entire store.
@ -37,9 +38,9 @@ type stateStore struct {
mkdirErr error
}
// bigLock acquires fileMu on stateStore.
// bigLock acquires fileMu on [Store].
// A non-nil error returned by bigLock is of type [hst.AppError].
func (s *stateStore) bigLock() (unlock func(), err error) {
func (s *Store) bigLock() (unlock func(), err error) {
s.mkdirOnce.Do(func() { s.mkdirErr = os.MkdirAll(s.base.String(), 0700) })
if s.mkdirErr != nil {
return nil, &hst.AppError{Step: "create state store directory", Err: s.mkdirErr}
@ -51,14 +52,14 @@ func (s *stateStore) bigLock() (unlock func(), err error) {
return
}
// identityHandle loads or initialises a storeHandle for identity.
// A non-nil error returned by identityHandle is of type [hst.AppError].
func (s *stateStore) identityHandle(identity int) (*storeHandle, error) {
h := new(storeHandle)
// Handle loads or initialises a [Handle] for identity.
// A non-nil error returned by Handle is of type [hst.AppError].
func (s *Store) Handle(identity int) (*Handle, error) {
h := newHandle(s.base, identity)
h.mu.Lock()
if v, ok := s.handles.LoadOrStore(identity, h); ok {
h = v.(*storeHandle)
h = v.(*Handle)
} else {
// acquire big lock to initialise previously unknown segment handle
if unlock, err := s.bigLock(); err != nil {
@ -67,11 +68,7 @@ func (s *stateStore) identityHandle(identity int) (*storeHandle, error) {
defer unlock()
}
h.identity = identity
h.path = s.base.Append(strconv.Itoa(identity))
h.fileMu = lockedfile.MutexAt(h.path.Append(storeMutexName).String())
err := os.MkdirAll(h.path.String(), 0700)
err := os.MkdirAll(h.Path.String(), 0700)
h.mu.Unlock()
if err != nil && !errors.Is(err, fs.ErrExist) {
// handle methods will likely return ENOENT
@ -82,18 +79,18 @@ func (s *stateStore) identityHandle(identity int) (*storeHandle, error) {
return h, nil
}
// segmentIdentity is produced by the iterator returned by stateStore.segments.
type segmentIdentity struct {
// SegmentIdentity is produced by the iterator returned by [Store.Segments].
type SegmentIdentity struct {
// Identity of the current segment.
identity int
Identity int
// Error encountered while processing this segment.
err error
Err error
}
// segments returns an iterator over all segmentIdentity known to the store.
// To obtain a storeHandle on a segment, caller must then call identityHandle.
// Segments returns an iterator over all [SegmentIdentity] known to the [Store].
// To obtain a [Handle] on a segment, caller must then call [Store.Handle].
// A non-nil error returned by segments is of type [hst.AppError].
func (s *stateStore) segments() (iter.Seq[segmentIdentity], int, error) {
func (s *Store) Segments() (iter.Seq[SegmentIdentity], int, error) {
// read directory contents, should only contain storeMutexName and identity
var entries []os.DirEntry
@ -115,36 +112,36 @@ func (s *stateStore) segments() (iter.Seq[segmentIdentity], int, error) {
l--
}
return func(yield func(segmentIdentity) bool) {
return func(yield func(SegmentIdentity) bool) {
// for error reporting
const step = "process store segment"
for _, ent := range entries {
si := segmentIdentity{identity: -1}
si := SegmentIdentity{Identity: -1}
// should only be the big lock
if !ent.IsDir() {
if ent.Name() == storeMutexName {
if ent.Name() == MutexName {
continue
}
// this should never happen
si.err = &hst.AppError{Step: step, Err: syscall.EISDIR,
si.Err = &hst.AppError{Step: step, Err: syscall.EISDIR,
Msg: "skipped non-directory entry " + strconv.Quote(ent.Name())}
goto out
}
// failure paths either indicates a serious bug or external interference
if v, err := strconv.Atoi(ent.Name()); err != nil {
si.err = &hst.AppError{Step: step, Err: err,
si.Err = &hst.AppError{Step: step, Err: err,
Msg: "skipped non-identity entry " + strconv.Quote(ent.Name())}
goto out
} else if v < hst.IdentityMin || v > hst.IdentityMax {
si.err = &hst.AppError{Step: step, Err: syscall.ERANGE,
si.Err = &hst.AppError{Step: step, Err: syscall.ERANGE,
Msg: "skipped out of bounds entry " + strconv.Itoa(v)}
goto out
} else {
si.identity = v
si.Identity = v
}
out:
@ -155,8 +152,8 @@ func (s *stateStore) segments() (iter.Seq[segmentIdentity], int, error) {
}, l, nil
}
// newStore returns the address of a new instance of stateStore.
// Multiple instances of stateStore rooted in the same directory is supported, but discouraged.
func newStore(base *check.Absolute) *stateStore {
return &stateStore{base: base, fileMu: lockedfile.MutexAt(base.Append(storeMutexName).String())}
// New returns the address of a new instance of [Store].
// Multiple instances of [Store] rooted in the same directory is possible, but unsupported.
func New(base *check.Absolute) *Store {
return &Store{base: base, fileMu: lockedfile.MutexAt(base.Append(MutexName).String())}
}

83
internal/store/store_test.go
View File

@ -1,4 +1,4 @@
package store
package store_test
import (
"cmp"
@ -10,18 +10,23 @@ import (
"strings"
"syscall"
"testing"
_ "unsafe"
"hakurei.app/container/check"
"hakurei.app/hst"
"hakurei.app/internal/store"
)
//go:linkname bigLock hakurei.app/internal/store.(*Store).bigLock
func bigLock(s *store.Store) (unlock func(), err error)
func TestStateStoreBigLock(t *testing.T) {
t.Parallel()
{
s := newStore(check.MustAbs(t.TempDir()).Append("state"))
s := store.New(check.MustAbs(t.TempDir()).Append("state"))
for i := 0; i < 2; i++ { // check once behaviour
if unlock, err := s.bigLock(); err != nil {
if unlock, err := bigLock(s); err != nil {
t.Fatalf("bigLock: error = %v", err)
} else {
unlock()
@ -35,7 +40,7 @@ func TestStateStoreBigLock(t *testing.T) {
wantErr := &hst.AppError{Step: "create state store directory",
Err: &os.PathError{Op: "mkdir", Path: "/proc/nonexistent", Err: syscall.ENOENT}}
for i := 0; i < 2; i++ { // check once behaviour
if _, err := newStore(check.MustAbs("/proc/nonexistent")).bigLock(); !reflect.DeepEqual(err, wantErr) {
if _, err := bigLock(store.New(check.MustAbs("/proc/nonexistent"))); !reflect.DeepEqual(err, wantErr) {
t.Errorf("bigLock: error = %#v, want %#v", err, wantErr)
}
}
@ -50,35 +55,35 @@ func TestStateStoreBigLock(t *testing.T) {
}
wantErr := &hst.AppError{Step: "acquire lock on the state store",
Err: &os.PathError{Op: "open", Path: base.Append(storeMutexName).String(), Err: syscall.EACCES}}
if _, err := newStore(base).bigLock(); !reflect.DeepEqual(err, wantErr) {
Err: &os.PathError{Op: "open", Path: base.Append(store.MutexName).String(), Err: syscall.EACCES}}
if _, err := bigLock(store.New(base)); !reflect.DeepEqual(err, wantErr) {
t.Errorf("bigLock: error = %#v, want %#v", err, wantErr)
}
})
}
func TestStateStoreIdentityHandle(t *testing.T) {
func TestStateStoreHandle(t *testing.T) {
t.Parallel()
t.Run("loadstore", func(t *testing.T) {
t.Parallel()
s := newStore(check.MustAbs(t.TempDir()).Append("store"))
s := store.New(check.MustAbs(t.TempDir()).Append("store"))
var handleAddr [8]*storeHandle
var handleAddr [8]*store.Handle
checkHandle := func(identity int, load bool) {
if h, err := s.identityHandle(identity); err != nil {
t.Fatalf("identityHandle: error = %v", err)
if h, err := s.Handle(identity); err != nil {
t.Fatalf("Handle: error = %v", err)
} else if load != (handleAddr[identity] != nil) {
t.Fatalf("identityHandle: load = %v, want %v", load, handleAddr[identity] != nil)
t.Fatalf("Handle: load = %v, want %v", load, handleAddr[identity] != nil)
} else if !load {
handleAddr[identity] = h
if h.identity != identity {
t.Errorf("identityHandle: identity = %d, want %d", h.identity, identity)
if h.Identity != identity {
t.Errorf("Handle: identity = %d, want %d", h.Identity, identity)
}
} else if h != handleAddr[identity] {
t.Fatalf("identityHandle: %p, want %p", h, handleAddr[identity])
t.Fatalf("Handle: %p, want %p", h, handleAddr[identity])
}
}
@ -103,9 +108,9 @@ func TestStateStoreIdentityHandle(t *testing.T) {
}
wantErr := &hst.AppError{Step: "acquire lock on the state store",
Err: &os.PathError{Op: "open", Path: base.Append(storeMutexName).String(), Err: syscall.EACCES}}
if _, err := newStore(base).identityHandle(0); !reflect.DeepEqual(err, wantErr) {
t.Errorf("identityHandle: error = %#v, want %#v", err, wantErr)
Err: &os.PathError{Op: "open", Path: base.Append(store.MutexName).String(), Err: syscall.EACCES}}
if _, err := store.New(base).Handle(0); !reflect.DeepEqual(err, wantErr) {
t.Errorf("Handle: error = %#v, want %#v", err, wantErr)
}
})
@ -116,7 +121,7 @@ func TestStateStoreIdentityHandle(t *testing.T) {
if err := os.MkdirAll(base.String(), 0700); err != nil {
t.Fatal(err.Error())
}
if f, err := os.Create(base.Append(storeMutexName).String()); err != nil {
if f, err := os.Create(base.Append(store.MutexName).String()); err != nil {
t.Fatal(err.Error())
} else if err = f.Close(); err != nil {
t.Fatal(err.Error())
@ -132,8 +137,8 @@ func TestStateStoreIdentityHandle(t *testing.T) {
wantErr := &hst.AppError{Step: "create store segment directory",
Err: &os.PathError{Op: "mkdir", Path: base.Append("0").String(), Err: syscall.EACCES}}
if _, err := newStore(base).identityHandle(0); !reflect.DeepEqual(err, wantErr) {
t.Errorf("identityHandle: error = %#v, want %#v", err, wantErr)
if _, err := store.New(base).Handle(0); !reflect.DeepEqual(err, wantErr) {
t.Errorf("Handle: error = %#v, want %#v", err, wantErr)
}
})
}
@ -144,8 +149,8 @@ func TestStateStoreSegments(t *testing.T) {
testCases := []struct {
name string
ents [2][]string
want []segmentIdentity
ext func(t *testing.T, segments iter.Seq[segmentIdentity], n int)
want []store.SegmentIdentity
ext func(t *testing.T, segments iter.Seq[store.SegmentIdentity], n int)
}{
{"errors", [2][]string{{
"f0-invalid-file",
@ -153,7 +158,7 @@ func TestStateStoreSegments(t *testing.T) {
"f1-invalid-syntax",
"9999",
"16384",
}}, []segmentIdentity{
}}, []store.SegmentIdentity{
{-1, &hst.AppError{Step: "process store segment", Err: syscall.EISDIR,
Msg: `skipped non-directory entry "f0-invalid-file"`}},
{-1, &hst.AppError{Step: "process store segment", Err: syscall.ERANGE,
@ -180,7 +185,7 @@ func TestStateStoreSegments(t *testing.T) {
"20",
"31",
"197",
}}, []segmentIdentity{
}}, []store.SegmentIdentity{
{0, nil},
{1, nil},
{2, nil},
@ -194,9 +199,9 @@ func TestStateStoreSegments(t *testing.T) {
{20, nil},
{31, nil},
{197, nil},
}, func(t *testing.T, segments iter.Seq[segmentIdentity], n int) {
}, func(t *testing.T, segments iter.Seq[store.SegmentIdentity], n int) {
if n != 13 {
t.Fatalf("segments: n = %d", n)
t.Fatalf("Segments: n = %d", n)
}
// check partial drain
@ -215,24 +220,24 @@ func TestStateStoreSegments(t *testing.T) {
}
createEntries(t, base, tc.ents)
var got []segmentIdentity
if segments, n, err := newStore(base).segments(); err != nil {
t.Fatalf("segments: error = %v", err)
var got []store.SegmentIdentity
if segments, n, err := store.New(base).Segments(); err != nil {
t.Fatalf("Segments: error = %v", err)
} else {
got = slices.AppendSeq(make([]segmentIdentity, 0, n), segments)
got = slices.AppendSeq(make([]store.SegmentIdentity, 0, n), segments)
if tc.ext != nil {
tc.ext(t, segments, n)
}
}
slices.SortFunc(got, func(a, b segmentIdentity) int {
if a.identity == b.identity {
return strings.Compare(a.err.Error(), b.err.Error())
slices.SortFunc(got, func(a, b store.SegmentIdentity) int {
if a.Identity == b.Identity {
return strings.Compare(a.Err.Error(), b.Err.Error())
}
return cmp.Compare(a.identity, b.identity)
return cmp.Compare(a.Identity, b.Identity)
})
if !reflect.DeepEqual(got, tc.want) {
t.Errorf("segments: %#v, want %#v", got, tc.want)
t.Errorf("Segments: %#v, want %#v", got, tc.want)
}
})
}
@ -246,9 +251,9 @@ func TestStateStoreSegments(t *testing.T) {
}
wantErr := &hst.AppError{Step: "acquire lock on the state store",
Err: &os.PathError{Op: "open", Path: base.Append(storeMutexName).String(), Err: syscall.EACCES}}
if _, _, err := newStore(base).segments(); !reflect.DeepEqual(err, wantErr) {
t.Errorf("segments: error = %#v, want %#v", err, wantErr)
Err: &os.PathError{Op: "open", Path: base.Append(store.MutexName).String(), Err: syscall.EACCES}}
if _, _, err := store.New(base).Segments(); !reflect.DeepEqual(err, wantErr) {
t.Errorf("Segments: error = %#v, want %#v", err, wantErr)
}
})
}