hst/instance: define instance state

This is now part of the hst API. This change also improves identifier generation and serialisation.

Signed-off-by: Ophestra <cat@gensokyo.uk>

13 files changed, 41 insertions, 170 deletions

diff --git a/internal/app/app.go b/internal/app/app.go
index 4d9d2efe..03608517 100644
--- a/internal/app/app.go
+++ b/internal/app/app.go
@@ -7,15 +7,14 @@ import (
 	"os"
 
 	"hakurei.app/hst"
-	"hakurei.app/internal/app/state"
 	"hakurei.app/message"
 )
 
 // Main runs an app according to [hst.Config] and terminates. Main does not return.
 func Main(ctx context.Context, msg message.Msg, config *hst.Config) {
-	var id state.ID
-	if err := state.NewAppID(&id); err != nil {
-		log.Fatal(err)
+	var id hst.ID
+	if err := hst.NewInstanceID(&id); err != nil {
+		log.Fatal(err.Error())
 	}
 
 	seal := outcome{syscallDispatcher: direct{msg}}
diff --git a/internal/app/app_test.go b/internal/app/app_test.go
index b562f8ee..96113eb8 100644
--- a/internal/app/app_test.go
+++ b/internal/app/app_test.go
@@ -22,7 +22,6 @@ import (
 	"hakurei.app/container/fhs"
 	"hakurei.app/container/seccomp"
 	"hakurei.app/hst"
-	"hakurei.app/internal/app/state"
 	"hakurei.app/message"
 	"hakurei.app/system"
 	"hakurei.app/system/acl"
@@ -38,7 +37,7 @@ func TestApp(t *testing.T) {
 		name       string
 		k          syscallDispatcher
 		config     *hst.Config
-		id         state.ID
+		id         hst.ID
 		wantSys    *system.I
 		wantParams *container.Params
 	}{
@@ -212,7 +211,7 @@ func TestApp(t *testing.T) {
 			Args: []string{"/run/current-system/sw/bin/zsh"},
 
 			Flags: hst.FUserns | hst.FHostNet | hst.FHostAbstract | hst.FTty | hst.FShareRuntime | hst.FShareTmpdir,
-		}}, state.ID{
+		}}, hst.ID{
 			0x4a, 0x45, 0x0b, 0x65,
 			0x96, 0xd7, 0xbc, 0x15,
 			0xbd, 0x01, 0x78, 0x0e,
@@ -336,7 +335,7 @@ func TestApp(t *testing.T) {
 
 				Flags: hst.FUserns | hst.FHostNet | hst.FHostAbstract | hst.FTty | hst.FShareRuntime | hst.FShareTmpdir,
 			},
-		}, state.ID{
+		}, hst.ID{
 			0xeb, 0xf0, 0x83, 0xd1,
 			0xb1, 0x75, 0x91, 0x17,
 			0x82, 0xd4, 0x13, 0x36,
@@ -490,7 +489,7 @@ func TestApp(t *testing.T) {
 			DirectWayland: true,
 
 			Identity: 1, Groups: []string{},
-		}, state.ID{
+		}, hst.ID{
 			0x8e, 0x2c, 0x76, 0xb0,
 			0x66, 0xda, 0xbe, 0x57,
 			0x4c, 0xf0, 0x73, 0xbd,
diff --git a/internal/app/dispatcher_test.go b/internal/app/dispatcher_test.go
index a994d0b0..74f72b4b 100644
--- a/internal/app/dispatcher_test.go
+++ b/internal/app/dispatcher_test.go
@@ -21,7 +21,6 @@ import (
 	"hakurei.app/container/seccomp"
 	"hakurei.app/container/stub"
 	"hakurei.app/hst"
-	"hakurei.app/internal/app/state"
 	"hakurei.app/message"
 	"hakurei.app/system"
 )
@@ -49,7 +48,7 @@ const (
 )
 
 // checkExpectInstanceId is the [state.ID] value used by checkOpBehaviour to initialise outcomeState.
-var checkExpectInstanceId = *(*state.ID)(bytes.Repeat([]byte{0xaa}, len(state.ID{})))
+var checkExpectInstanceId = *(*hst.ID)(bytes.Repeat([]byte{0xaa}, len(hst.ID{})))
 
 type (
 	// pStateSysFunc is called before each test case is run to prepare outcomeStateSys.
diff --git a/internal/app/finalise.go b/internal/app/finalise.go
index 52a38faa..6cb4f586 100644
--- a/internal/app/finalise.go
+++ b/internal/app/finalise.go
@@ -9,7 +9,6 @@ import (
 	"sync/atomic"
 
 	"hakurei.app/hst"
-	"hakurei.app/internal/app/state"
 	"hakurei.app/message"
 	"hakurei.app/system"
 )
@@ -37,7 +36,7 @@ type outcome struct {
 	syscallDispatcher
 }
 
-func (k *outcome) finalise(ctx context.Context, msg message.Msg, id *state.ID, config *hst.Config) error {
+func (k *outcome) finalise(ctx context.Context, msg message.Msg, id *hst.ID, config *hst.Config) error {
 	if ctx == nil || id == nil {
 		// unreachable
 		panic("invalid call to finalise")
diff --git a/internal/app/outcome.go b/internal/app/outcome.go
index 30fd38ff..f462dfd5 100644
--- a/internal/app/outcome.go
+++ b/internal/app/outcome.go
@@ -8,7 +8,6 @@ import (
 	"hakurei.app/container"
 	"hakurei.app/container/check"
 	"hakurei.app/hst"
-	"hakurei.app/internal/app/state"
 	"hakurei.app/message"
 	"hakurei.app/system"
 	"hakurei.app/system/acl"
@@ -36,9 +35,9 @@ type outcomeState struct {
 	Shim *shimParams
 
 	// Generated and accounted for by the caller.
-	ID *state.ID
+	ID *hst.ID
 	// Copied from ID.
-	id *stringPair[state.ID]
+	id *stringPair[hst.ID]
 
 	// Copied from the [hst.Config] field of the same name.
 	Identity int
@@ -77,7 +76,7 @@ func (s *outcomeState) valid() bool {
 }
 
 // newOutcomeState returns the address of a new outcomeState with its exported fields populated via syscallDispatcher.
-func newOutcomeState(k syscallDispatcher, msg message.Msg, id *state.ID, config *hst.Config, hsu *Hsu) *outcomeState {
+func newOutcomeState(k syscallDispatcher, msg message.Msg, id *hst.ID, config *hst.Config, hsu *Hsu) *outcomeState {
 	s := outcomeState{
 		Shim:      &shimParams{PrivPID: k.getpid(), Verbose: msg.IsVerbose()},
 		ID:        id,
@@ -120,7 +119,7 @@ func (s *outcomeState) populateLocal(k syscallDispatcher, msg message.Msg) error
 	s.k = k
 	s.msg = msg
 
-	s.id = &stringPair[state.ID]{*s.ID, s.ID.String()}
+	s.id = &stringPair[hst.ID]{*s.ID, s.ID.String()}
 
 	s.Copy(&s.sc, s.UserID)
 	msg.Verbosef("process share directory at %q, runtime directory at %q", s.sc.SharePath, s.sc.RunDirPath)
diff --git a/internal/app/outcome_test.go b/internal/app/outcome_test.go
index 53c8958d..740e7db5 100644
--- a/internal/app/outcome_test.go
+++ b/internal/app/outcome_test.go
@@ -4,7 +4,6 @@ import (
 	"testing"
 
 	"hakurei.app/hst"
-	"hakurei.app/internal/app/state"
 )
 
 func TestOutcomeStateValid(t *testing.T) {
@@ -19,9 +18,9 @@ func TestOutcomeStateValid(t *testing.T) {
 		{"zero", new(outcomeState), false},
 		{"shim", &outcomeState{Shim: &shimParams{PrivPID: -1, Ops: []outcomeOp{}}, Container: new(hst.ContainerConfig), EnvPaths: new(EnvPaths)}, false},
 		{"id", &outcomeState{Shim: &shimParams{PrivPID: 1, Ops: []outcomeOp{}}, Container: new(hst.ContainerConfig), EnvPaths: new(EnvPaths)}, false},
-		{"container", &outcomeState{Shim: &shimParams{PrivPID: 1, Ops: []outcomeOp{}}, ID: new(state.ID), EnvPaths: new(EnvPaths)}, false},
-		{"envpaths", &outcomeState{Shim: &shimParams{PrivPID: 1, Ops: []outcomeOp{}}, ID: new(state.ID), Container: new(hst.ContainerConfig)}, false},
-		{"valid", &outcomeState{Shim: &shimParams{PrivPID: 1, Ops: []outcomeOp{}}, ID: new(state.ID), Container: new(hst.ContainerConfig), EnvPaths: new(EnvPaths)}, true},
+		{"container", &outcomeState{Shim: &shimParams{PrivPID: 1, Ops: []outcomeOp{}}, ID: new(hst.ID), EnvPaths: new(EnvPaths)}, false},
+		{"envpaths", &outcomeState{Shim: &shimParams{PrivPID: 1, Ops: []outcomeOp{}}, ID: new(hst.ID), Container: new(hst.ContainerConfig)}, false},
+		{"valid", &outcomeState{Shim: &shimParams{PrivPID: 1, Ops: []outcomeOp{}}, ID: new(hst.ID), Container: new(hst.ContainerConfig), EnvPaths: new(EnvPaths)}, true},
 	}
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
diff --git a/internal/app/process.go b/internal/app/process.go
index 0962e212..f71479bc 100644
--- a/internal/app/process.go
+++ b/internal/app/process.go
@@ -289,7 +289,7 @@ func (k *outcome) main(msg message.Msg) {
 
 	// shim accepted setup payload, create process state
 	if ok, err := ms.store.Do(k.state.identity.unwrap(), func(c state.Cursor) {
-		if err := c.Save(&state.State{
+		if err := c.Save(&hst.State{
 			ID:     k.state.id.unwrap(),
 			PID:    ms.cmd.Process.Pid,
 			Config: k.config,
diff --git a/internal/app/state/id.go b/internal/app/state/id.go
deleted file mode 100644
index 11bbc3fe..00000000
--- a/internal/app/state/id.go
+++ /dev/null
@@ -1,48 +0,0 @@
-package state
-
-import (
-	"crypto/rand"
-	"encoding/hex"
-	"errors"
-	"fmt"
-)
-
-type ID [16]byte
-
-var (
-	ErrInvalidLength = errors.New("string representation must have a length of 32")
-)
-
-func (a *ID) String() string {
-	return hex.EncodeToString(a[:])
-}
-
-func NewAppID(id *ID) error {
-	_, err := rand.Read(id[:])
-	return err
-}
-
-func ParseAppID(id *ID, s string) error {
-	if len(s) != 32 {
-		return ErrInvalidLength
-	}
-
-	for i, b := range s {
-		if b < '0' || b > 'f' {
-			return fmt.Errorf("invalid char %q at byte %d", b, i)
-		}
-
-		v := uint8(b)
-		if v > '9' {
-			v = 10 + v - 'a'
-		} else {
-			v -= '0'
-		}
-		if i%2 == 0 {
-			v <<= 4
-		}
-		id[i/2] += v
-	}
-
-	return nil
-}
diff --git a/internal/app/state/id_test.go b/internal/app/state/id_test.go
deleted file mode 100644
index abf2c190..00000000
--- a/internal/app/state/id_test.go
+++ /dev/null
@@ -1,63 +0,0 @@
-package state_test
-
-import (
-	"errors"
-	"testing"
-
-	"hakurei.app/internal/app/state"
-)
-
-func TestParseAppID(t *testing.T) {
-	t.Run("bad length", func(t *testing.T) {
-		if err := state.ParseAppID(new(state.ID), "meow"); !errors.Is(err, state.ErrInvalidLength) {
-			t.Errorf("ParseAppID: error = %v, wantErr =  %v", err, state.ErrInvalidLength)
-		}
-	})
-
-	t.Run("bad byte", func(t *testing.T) {
-		wantErr := "invalid char '\\n' at byte 15"
-		if err := state.ParseAppID(new(state.ID), "02bc7f8936b2af6\n\ne2535cd71ef0bb7"); err == nil || err.Error() != wantErr {
-			t.Errorf("ParseAppID: error = %v, wantErr =  %v", err, wantErr)
-		}
-	})
-
-	t.Run("fuzz 16 iterations", func(t *testing.T) {
-		for i := 0; i < 16; i++ {
-			testParseAppIDWithRandom(t)
-		}
-	})
-}
-
-func FuzzParseAppID(f *testing.F) {
-	for i := 0; i < 16; i++ {
-		id := new(state.ID)
-		if err := state.NewAppID(id); err != nil {
-			panic(err.Error())
-		}
-		f.Add(id[0], id[1], id[2], id[3], id[4], id[5], id[6], id[7], id[8], id[9], id[10], id[11], id[12], id[13], id[14], id[15])
-	}
-
-	f.Fuzz(func(t *testing.T, b0, b1, b2, b3, b4, b5, b6, b7, b8, b9, b10, b11, b12, b13, b14, b15 byte) {
-		testParseAppID(t, &state.ID{b0, b1, b2, b3, b4, b5, b6, b7, b8, b9, b10, b11, b12, b13, b14, b15})
-	})
-}
-
-func testParseAppIDWithRandom(t *testing.T) {
-	id := new(state.ID)
-	if err := state.NewAppID(id); err != nil {
-		t.Fatalf("cannot generate app ID: %v", err)
-	}
-	testParseAppID(t, id)
-}
-
-func testParseAppID(t *testing.T, id *state.ID) {
-	s := id.String()
-	got := new(state.ID)
-	if err := state.ParseAppID(got, s); err != nil {
-		t.Fatalf("cannot parse app ID: %v", err)
-	}
-
-	if *got != *id {
-		t.Fatalf("ParseAppID(%#v) = \n%#v, want \n%#v", s, got, id)
-	}
-}
diff --git a/internal/app/state/join.go b/internal/app/state/join.go
index 2b4011fe..43a19b1d 100644
--- a/internal/app/state/join.go
+++ b/internal/app/state/join.go
@@ -3,6 +3,8 @@ package state
 import (
 	"errors"
 	"maps"
+
+	"hakurei.app/hst"
 )
 
 var (
@@ -14,20 +16,22 @@ Joiner is the interface that wraps the Join method.
 
 The Join function uses Joiner if available.
 */
-type Joiner interface{ Join() (Entries, error) }
+type Joiner interface {
+	Join() (map[hst.ID]*hst.State, error)
+}
 
-// Join returns joined state entries of all active aids.
-func Join(s Store) (Entries, error) {
+// Join returns joined state entries of all active identities.
+func Join(s Store) (map[hst.ID]*hst.State, error) {
 	if j, ok := s.(Joiner); ok {
 		return j.Join()
 	}
 
 	var (
 		aids    []int
-		entries = make(Entries)
+		entries = make(map[hst.ID]*hst.State)
 
 		el      int
-		res     Entries
+		res     map[hst.ID]*hst.State
 		loadErr error
 	)
 
diff --git a/internal/app/state/multi.go b/internal/app/state/multi.go
index ca608f58..c15b8534 100644
--- a/internal/app/state/multi.go
+++ b/internal/app/state/multi.go
@@ -131,7 +131,7 @@ type multiBackend struct {
 	mu sync.RWMutex
 }
 
-func (b *multiBackend) filename(id *ID) string { return path.Join(b.path, id.String()) }
+func (b *multiBackend) filename(id *hst.ID) string { return path.Join(b.path, id.String()) }
 
 func (b *multiBackend) lockFileAct(lt int) (err error) {
 	op := "LockAct"
@@ -163,7 +163,7 @@ func (b *multiBackend) unlockFile() error { return b.lockFileAct(syscall.LOCK_UN
 
 // reads all launchers in simpleBackend
 // file contents are ignored if decode is false
-func (b *multiBackend) load(decode bool) (Entries, error) {
+func (b *multiBackend) load(decode bool) (map[hst.ID]*hst.State, error) {
 	b.mu.RLock()
 	defer b.mu.RUnlock()
 
@@ -177,15 +177,15 @@ func (b *multiBackend) load(decode bool) (Entries, error) {
 
 	// allocate as if every entry is valid
 	// since that should be the case assuming no external interference happens
-	r := make(Entries, len(entries))
+	r := make(map[hst.ID]*hst.State, len(entries))
 
 	for _, e := range entries {
 		if e.IsDir() {
 			return nil, fmt.Errorf("unexpected directory %q in store", e.Name())
 		}
 
-		var id ID
-		if err := ParseAppID(&id, e.Name()); err != nil {
+		var id hst.ID
+		if err := id.UnmarshalText([]byte(e.Name())); err != nil {
 			return nil, &hst.AppError{Step: "parse state key", Err: err}
 		}
 
@@ -195,7 +195,7 @@ func (b *multiBackend) load(decode bool) (Entries, error) {
 			if f, err := os.Open(path.Join(b.path, e.Name())); err != nil {
 				return &hst.AppError{Step: "open state file", Err: err}
 			} else {
-				var s State
+				var s hst.State
 				r[id] = &s
 
 				// append regardless, but only parse if required, implements Len
@@ -226,7 +226,7 @@ func (b *multiBackend) load(decode bool) (Entries, error) {
 }
 
 // Save writes process state to filesystem
-func (b *multiBackend) Save(state *State) error {
+func (b *multiBackend) Save(state *hst.State) error {
 	b.mu.Lock()
 	defer b.mu.Unlock()
 
@@ -247,7 +247,7 @@ func (b *multiBackend) Save(state *State) error {
 	return nil
 }
 
-func (b *multiBackend) Destroy(id ID) error {
+func (b *multiBackend) Destroy(id hst.ID) error {
 	b.mu.Lock()
 	defer b.mu.Unlock()
 
@@ -257,7 +257,7 @@ func (b *multiBackend) Destroy(id ID) error {
 	return nil
 }
 
-func (b *multiBackend) Load() (Entries, error) { return b.load(true) }
+func (b *multiBackend) Load() (map[hst.ID]*hst.State, error) { return b.load(true) }
 
 func (b *multiBackend) Len() (int, error) {
 	// rn consists of only nil entries but has the correct length
diff --git a/internal/app/state/state.go b/internal/app/state/state.go
index b8d8d255..ef783bfb 100644
--- a/internal/app/state/state.go
+++ b/internal/app/state/state.go
@@ -3,7 +3,6 @@ package state
 
 import (
 	"errors"
-	"time"
 
 	"hakurei.app/hst"
 )
@@ -11,8 +10,6 @@ import (
 // ErrNoConfig is returned by [Cursor] when used with a nil [hst.Config].
 var ErrNoConfig = errors.New("state does not contain config")
 
-type Entries map[ID]*State
-
 type Store interface {
 	// Do calls f exactly once and ensures store exclusivity until f returns.
 	// Returns whether f is called and any errors during the locking process.
@@ -29,21 +26,8 @@ type Store interface {
 
 // Cursor provides access to the store of an identity.
 type Cursor interface {
-	Save(state *State) error
-	Destroy(id ID) error
-	Load() (Entries, error)
+	Save(state *hst.State) error
+	Destroy(id hst.ID) error
+	Load() (map[hst.ID]*hst.State, error)
 	Len() (int, error)
 }
-
-// State is the on-disk state of a container instance.
-type State struct {
-	// Unique instance id, generated by internal/app.
-	ID ID `json:"instance"`
-	// Shim process pid. This runs as the target user.
-	PID int `json:"pid"`
-	// Configuration value used to start the container.
-	Config *hst.Config `json:"config"`
-
-	// Exact point in time that the shim process was created.
-	Time time.Time `json:"time"`
-}
diff --git a/internal/app/state/state_test.go b/internal/app/state/state_test.go
index baada60d..2e191f31 100644
--- a/internal/app/state/state_test.go
+++ b/internal/app/state/state_test.go
@@ -28,7 +28,7 @@ func testStore(t *testing.T, s state.Store) {
 		tl
 	)
 
-	var tc [tl]state.State
+	var tc [tl]hst.State
 	for i := 0; i < tl; i++ {
 		makeState(t, &tc[i])
 	}
@@ -122,8 +122,8 @@ func testStore(t *testing.T, s state.Store) {
 	})
 }
 
-func makeState(t *testing.T, s *state.State) {
-	if err := state.NewAppID(&s.ID); err != nil {
+func makeState(t *testing.T, s *hst.State) {
+	if err := hst.NewInstanceID(&s.ID); err != nil {
 		t.Fatalf("cannot create dummy state: %v", err)
 	}
 	s.PID = rand.Int()