treewide: document linkname uses

These provide justification for each use of linkname. Poorly thought out uses of linkname are removed.

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

internal/store/data_test.go

@@ -27,7 +27,7 @@ func TestEntryData(t *testing.T) {
 			return buf.String()
 		}
 	}
-	templateStateGob := mustEncodeGob(newTemplateState())
+	templateStateGob := mustEncodeGob(NewTemplateState())
 
 	testCases := []struct {
 		name string
@@ -45,11 +45,11 @@ func TestEntryData(t *testing.T) {
 			Step: "validate configuration", Err: hst.ErrConfigNull,
 			Msg: "invalid configuration"}},
 
-		{"inconsistent enablement", "\x00\xff\xca\xfe\x00\x00\xff\x00" + templateStateGob, newTemplateState(), &hst.AppError{
+		{"inconsistent enablement", "\x00\xff\xca\xfe\x00\x00\xff\x00" + templateStateGob, NewTemplateState(), &hst.AppError{
 			Step: "validate state enablement", Err: os.ErrInvalid,
 			Msg: "state entry aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa has unexpected enablement byte 0xd, 0xff"}},
 
-		{"template", "\x00\xff\xca\xfe\x00\x00\x0d\xf2" + templateStateGob, newTemplateState(), nil},
+		{"template", "\x00\xff\xca\xfe\x00\x00\x0d\xf2" + templateStateGob, NewTemplateState(), nil},
 	}
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
@@ -105,7 +105,7 @@ func TestEntryData(t *testing.T) {
 
 	t.Run("encode fault", func(t *testing.T) {
 		t.Parallel()
-		s := newTemplateState()
+		s := NewTemplateState()
 
 		t.Run("gob", func(t *testing.T) {
 			var want = &hst.AppError{Step: "encode state body", Err: stub.UniqueError(0xcafe)}
@@ -123,8 +123,8 @@ func TestEntryData(t *testing.T) {
 	})
 }
 
-// newTemplateState returns the address of a new template [hst.State] struct.
-func newTemplateState() *hst.State {
+// NewTemplateState returns the address of a new template [hst.State] struct.
+func NewTemplateState() *hst.State {
 	return &hst.State{
 		ID:      hst.ID(bytes.Repeat([]byte{0xaa}, len(hst.ID{}))),
 		PID:     0xcafe,

internal/store/segment_test.go

@@ -10,7 +10,7 @@ import (
 	"strings"
 	"syscall"
 	"testing"
-	_ "unsafe"
+	_ "unsafe" // for go:linkname
 
 	"hakurei.app/container/check"
 	"hakurei.app/container/stub"
@@ -18,18 +18,23 @@ import (
 	"hakurei.app/internal/store"
 )
 
-//go:linkname newTemplateState hakurei.app/internal/store.newTemplateState
-func newTemplateState() *hst.State
-
+// Made available here for direct validation of state entry files.
+//
 //go:linkname entryDecode hakurei.app/internal/store.entryDecode
 func entryDecode(r io.Reader, p *hst.State) (hst.Enablement, error)
 
+// Made available here for direct access to known segment handles.
+//
 //go:linkname newHandle hakurei.app/internal/store.newHandle
 func newHandle(base *check.Absolute, identity int) *store.Handle
 
+// Made available here to check open error handling behaviour.
+//
 //go:linkname open hakurei.app/internal/store.(*EntryHandle).open
 func open(eh *store.EntryHandle, flag int, perm os.FileMode) (*os.File, error)
 
+// Made available here to check the saveload cycle.
+//
 //go:linkname save hakurei.app/internal/store.(*EntryHandle).save
 func save(eh *store.EntryHandle, state *hst.State) error
 
@@ -91,9 +96,9 @@ func TestStateEntryHandle(t *testing.T) {
 	t.Run("saveload", func(t *testing.T) {
 		t.Parallel()
 		eh := store.EntryHandle{Pathname: check.MustAbs(t.TempDir()).Append("entry"),
-			ID: newTemplateState().ID}
+			ID: store.NewTemplateState().ID}
 
-		if err := save(&eh, newTemplateState()); err != nil {
+		if err := save(&eh, store.NewTemplateState()); err != nil {
 			t.Fatalf("save: error = %v", err)
 		}
 
@@ -112,7 +117,7 @@ func TestStateEntryHandle(t *testing.T) {
 					t.Fatal(f.Close())
 				}
 
-				if want := newTemplateState(); !reflect.DeepEqual(&got, want) {
+				if want := store.NewTemplateState(); !reflect.DeepEqual(&got, want) {
 					t.Errorf("entryDecode: %#v, want %#v", &got, want)
 				}
 			})
@@ -122,7 +127,7 @@ func TestStateEntryHandle(t *testing.T) {
 
 				if et, err := eh.Load(nil); err != nil {
 					t.Fatalf("load: error = %v", err)
-				} else if want := newTemplateState().Enablements.Unwrap(); et != want {
+				} else if want := store.NewTemplateState().Enablements.Unwrap(); et != want {
 					t.Errorf("load: et = %x, want %x", et, want)
 				}
 			})
@@ -133,7 +138,7 @@ func TestStateEntryHandle(t *testing.T) {
 				var got hst.State
 				if _, err := eh.Load(&got); err != nil {
 					t.Fatalf("load: error = %v", err)
-				} else if want := newTemplateState(); !reflect.DeepEqual(&got, want) {
+				} else if want := store.NewTemplateState(); !reflect.DeepEqual(&got, want) {
 					t.Errorf("load: %#v, want %#v", &got, want)
 				}
 			})

internal/store/store_test.go

@@ -12,13 +12,15 @@ import (
 	"syscall"
 	"testing"
 	"time"
-	_ "unsafe"
+	_ "unsafe" // for go:linkname
 
 	"hakurei.app/container/check"
 	"hakurei.app/hst"
 	"hakurei.app/internal/store"
 )
 
+// Made available here to check bigLock error handling behaviour.
+//
 //go:linkname bigLock hakurei.app/internal/store.(*Store).bigLock
 func bigLock(s *store.Store) (unlock func(), err error)