@synopackageland/cli 0.4.0 → 0.5.0

package/dist/templates/native-go/backend/internal/helper/cohort.go

@@ -0,0 +1,393 @@
+package helper
+
+import (
+	"context"
+	"syscall"
+	"time"
+)
+
+// Staged root-side API. Only the supervisor owner loop calls these methods;
+// native adapters, grant/ACL authority and a public data transport are NOT installed.
+// Operation children are fixed synthetic operations, never caller executables.
+type operationBinding struct {
+	Inventory     Inventory `json:"inventory"`
+	Epoch         string    `json:"epoch"`
+	OperationID   string    `json:"operationId"`
+	Nonce         string    `json:"nonce"`
+	GrantID       string    `json:"grantId"`
+	GrantRevision uint64    `json:"grantRevision"`
+}
+type operationPeer struct {
+	PID int
+	UID uint32
+}
+type operationProcess interface {
+	supervisedChild
+	chunk(uint32) error
+	idle() (bool, error)
+	stopRelay()
+	relayStopped() bool
+}
+type cohortOperation struct {
+	binding        operationBinding
+	actor          NativeActor
+	process        operationProcess
+	bytes          uint64
+	canceled       bool
+	admittedAt     time.Time
+	lastActivity   time.Time
+	maxBytes       uint64
+	segments       []string
+	commitReserved bool
+	writeWork      *writeWork
+	work           *readOnlyWork
+	root           readOnlyRootWitness
+}
+type CohortCompletion struct {
+	Started             uint64 `json:"started"`
+	Reaped              uint64 `json:"reaped"`
+	WriteIntents        uint64 `json:"writeIntents,omitempty"`
+	WriteEffectsUnknown bool   `json:"writeEffectsUnknown,omitempty"`
+	RelaysStopped       bool   `json:"relaysStopped"`
+}
+
+func (q CohortCompletion) valid() bool {
+	return q.Started > 0 && q.Started <= MaxReplayEntries && q.Started == q.Reaped && q.RelaysStopped && q.WriteIntents <= q.Started && (!q.WriteEffectsUnknown || q.WriteIntents > 0)
+}
+
+type operationCohort struct {
+	inventory       Inventory
+	epoch           string
+	helperPID       int
+	helperLive      func() bool
+	gate            *admission
+	now             func() time.Time
+	startChild      func(NativeActor, operationBinding) (operationProcess, error)
+	operations      map[string]*cohortOperation
+	seen            map[string]bool
+	started, reaped uint64
+	receipts        map[string]cohortReceipt
+	fenced          bool
+}
+
+func newOperationCohort(i Inventory, epoch string, pid int, g *admission, live func() bool) *operationCohort {
+	return &operationCohort{inventory: i, epoch: epoch, helperPID: pid, gate: g, helperLive: live, now: time.Now, operations: map[string]*cohortOperation{}, seen: map[string]bool{}, receipts: map[string]cohortReceipt{}}
+}
+func (c *operationCohort) peerAllowed(p operationPeer) bool {
+	return c.helperPID > 1 && p.PID == c.helperPID && p.UID == 0 && c.helperLive != nil && c.helperLive()
+}
+func (c *operationCohort) bound(b operationBinding) bool {
+	return c.inventory.Protocol == DataProtocol && c.inventory.Valid() && b.Inventory == c.inventory && b.Epoch == c.epoch && digestPattern.MatchString(c.epoch) && digestPattern.MatchString(b.OperationID) && digestPattern.MatchString(b.Nonce) && digestPattern.MatchString(b.GrantID) && b.GrantRevision > 0
+}
+
+// Called with the observer's mutex held, including child/lease admission.
+func (c *operationCohort) allowed() bool {
+	if c.now().Before(c.gate.seen) {
+		c.gate.fenceLocked("observation-expired")
+	}
+	return !c.fenced && c.gate.allowLocked(c.now())
+}
+func (c *operationCohort) start(ctx context.Context, peer operationPeer, p *NativeProvider, carriers SessionCarriers, old NativeActor, b operationBinding) Code {
+	if c.fenced {
+		return ErrFenced
+	}
+	if !c.peerAllowed(peer) {
+		return ErrDenied
+	}
+	if !c.bound(b) {
+		return ErrInvalid
+	}
+	if !old.valid || old.UID() == 0 || old.GID() == 0 || old.account.Groups == nil {
+		return ErrDenied
+	}
+	actor, code := p.Revalidate(ctx, carriers, old)
+	if code != "" {
+		return code
+	}
+	c.gate.mu.Lock()
+	op, code := c.reserveLocked(actor, b)
+	c.gate.mu.Unlock()
+	if code != "" {
+		return code
+	}
+	return c.launchReserved(op)
+}
+
+// Only registers a slot and replay history. No child/bootstrap/I/O under locks.
+func (c *operationCohort) reserveLocked(actor NativeActor, b operationBinding) (*cohortOperation, Code) {
+	if !c.allowed() {
+		return nil, ErrFenced
+	}
+	if !c.bound(b) || !actor.valid || actor.UID() == 0 || actor.GID() == 0 || actor.account.Groups == nil {
+		return nil, ErrDenied
+	}
+	if !nativeFresh(actor.account.CheckedAt, c.now()) {
+		return nil, ErrStale
+	}
+	if c.seen["op:"+b.OperationID] || c.seen["nonce:"+b.Nonce] {
+		return nil, ErrReplay
+	}
+	count := 0
+	for _, op := range c.operations {
+		if op.actor.Principal().SubjectRef == actor.Principal().SubjectRef {
+			count++
+		}
+	}
+	if len(c.operations) >= MaxPackageOperations || count >= MaxSubjectOperations || len(c.seen) >= 2*MaxReplayEntries {
+		return nil, ErrBusy
+	}
+	if c.startChild == nil {
+		return nil, ErrUnavailable
+	}
+	op := &cohortOperation{binding: b, actor: actor, admittedAt: c.now(), maxBytes: MaxBoundedBytes}
+	c.operations[b.OperationID] = op
+	c.seen["op:"+b.OperationID] = true
+	c.seen["nonce:"+b.Nonce] = true
+	return op, ""
+}
+func (c *operationCohort) launchReserved(op *cohortOperation) Code {
+	c.gate.mu.Lock()
+	exists := c.operations[op.binding.OperationID] == op && !op.canceled && c.allowed()
+	if !exists {
+		delete(c.operations, op.binding.OperationID)
+	}
+	c.gate.mu.Unlock()
+	if !exists {
+		return ErrFenced
+	}
+	child, err := c.startChild(op.actor, op.binding)
+	c.gate.mu.Lock()
+	defer c.gate.mu.Unlock()
+	if child == nil {
+		delete(c.operations, op.binding.OperationID)
+		return ErrUnavailable
+	}
+	c.started++
+	op.process = child
+	if !c.allowed() {
+		op.canceled = true
+		child.stopRelay()
+		return ErrFenced
+	}
+	if err != nil {
+		op.canceled = true
+		child.stopRelay()
+		return ErrCleanupRequired
+	}
+	return ""
+}
+func (c *operationCohort) chunk(ctx context.Context, peer operationPeer, p *NativeProvider, carriers SessionCarriers, b operationBinding, n uint32) Code {
+	if c.fenced || !c.gate.allow(c.now()) {
+		return ErrFenced
+	}
+	if !c.peerAllowed(peer) {
+		return ErrDenied
+	}
+	op := c.operations[b.OperationID]
+	if op == nil || op.binding != b {
+		return ErrDenied
+	}
+	if op.canceled {
+		return ErrCanceled
+	}
+	if op.expired(c.now()) {
+		op.canceled = true
+		op.process.stopRelay()
+		return ErrTimeout
+	}
+	actor, code := p.Revalidate(ctx, carriers, op.actor)
+	if code != "" {
+		op.canceled = true
+		op.process.stopRelay()
+		return code
+	}
+	c.gate.mu.Lock()
+	code = c.reserveChunkLocked(op, actor, n)
+	c.gate.mu.Unlock()
+	if code != "" {
+		return code
+	}
+	return c.deliverChunk(op, n)
+}
+func (c *operationCohort) reserveChunkLocked(op *cohortOperation, actor NativeActor, n uint32) Code {
+	if !c.allowed() {
+		return ErrFenced
+	}
+	if op.process == nil || op.canceled {
+		return ErrCanceled
+	}
+	if op.expired(c.now()) {
+		op.canceled = true
+		op.process.stopRelay()
+		return ErrTimeout
+	}
+	if !nativeFresh(actor.account.CheckedAt, c.now()) {
+		op.canceled = true
+		op.process.stopRelay()
+		return ErrStale
+	}
+	ceiling := op.maxBytes
+	if ceiling == 0 {
+		ceiling = MaxBoundedBytes
+	}
+	if n == 0 || n > MaxChunkBytes || uint64(n) > ceiling || op.bytes > ceiling-uint64(n) {
+		return ErrLimit
+	}
+	idle, err := op.process.idle()
+	if err != nil {
+		op.canceled = true
+		op.process.stopRelay()
+		return ErrCleanupRequired
+	}
+	if !idle {
+		return ErrBusy
+	}
+	op.bytes += uint64(n)
+	op.actor = actor
+	op.lastActivity = c.now()
+	return ""
+}
+func (c *operationCohort) deliverChunk(op *cohortOperation, n uint32) Code {
+	if op.canceled {
+		return ErrCanceled
+	}
+	var err error
+	if p, ok := op.process.(interface {
+		chunkWithActor(uint32, NativeActor) error
+	}); ok {
+		err = p.chunkWithActor(n, op.actor)
+	} else {
+		err = op.process.chunk(n)
+	}
+	if err != nil {
+		op.canceled = true
+		op.process.stopRelay()
+		return ErrCleanupRequired
+	}
+	return ""
+}
+func (c *operationCohort) poll() error {
+	for id, op := range c.operations {
+		if op.process == nil {
+			if op.canceled {
+				delete(c.operations, id)
+			}
+			continue
+		}
+		if op.expired(c.now()) {
+			op.canceled = true
+			op.process.stopRelay()
+		}
+		if _, relayErr := op.process.idle(); relayErr != nil {
+			op.canceled = true
+			op.process.stopRelay()
+		}
+		done, err := op.process.exited()
+		if err != nil {
+			return err
+		}
+		if op.canceled && !done {
+			if err := op.process.signal(syscall.SIGKILL); err != nil {
+				return err
+			}
+		}
+		if done {
+			op.process.stopRelay()
+			if op.process.relayStopped() {
+				c.retire(id, op)
+			}
+		}
+	}
+	return nil
+}
+func (c *operationCohort) deny() {
+	c.fenced = true
+	for _, op := range c.operations {
+		op.canceled = true
+		if op.process != nil {
+			op.process.stopRelay()
+		}
+	}
+}
+func (c *operationCohort) drain(ctx context.Context, grace time.Duration) error {
+	c.deny()
+	return c.drainSelected(ctx, grace, func(*cohortOperation) bool { return true })
+}
+
+// S3 calls this after durable R; other grants keep running. This is only Q proof.
+func (c *operationCohort) cancelGrant(ctx context.Context, id string, revision uint64) error {
+	return c.drainSelected(ctx, TerminateGrace, func(op *cohortOperation) bool {
+		return op.binding.GrantID == id && op.binding.GrantRevision <= revision
+	})
+}
+func (c *operationCohort) drainSelected(ctx context.Context, grace time.Duration, selected func(*cohortOperation) bool) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	killed := map[string]bool{}
+	term := map[string]bool{}
+	escalate := time.Now().Add(grace)
+	for {
+		pending := false
+		for id, op := range c.operations {
+			if !selected(op) {
+				continue
+			}
+			op.canceled = true
+			if op.process == nil {
+				delete(c.operations, id)
+				continue
+			}
+			op.process.stopRelay()
+			done, err := op.process.exited()
+			if err != nil {
+				return err
+			}
+			if done {
+				if op.process.relayStopped() {
+					c.retire(id, op)
+					continue
+				}
+			} else if !term[id] {
+				if err := op.process.signal(syscall.SIGTERM); err != nil {
+					return err
+				}
+				term[id] = true
+			} else if !killed[id] && !time.Now().Before(escalate) {
+				if err := op.process.signal(syscall.SIGKILL); err != nil {
+					return err
+				}
+				killed[id] = true
+			}
+			pending = true
+		}
+		if !pending {
+			return nil
+		}
+		timer := time.NewTimer(time.Millisecond)
+		select {
+		case <-ctx.Done():
+			timer.Stop()
+			return ctx.Err()
+		case <-timer.C:
+		}
+	}
+}
+func (c *operationCohort) proof() (*CohortCompletion, error) {
+	if !c.fenced || len(c.operations) != 0 || c.started != c.reaped {
+		return nil, errTrust
+	}
+	if c.started == 0 {
+		return nil, nil
+	}
+	proof := &CohortCompletion{Started: c.started, Reaped: c.reaped, RelaysStopped: true}
+	for _, r := range c.receipts {
+		if r.write != nil {
+			proof.WriteIntents++
+			if r.write.unknown || r.write.code == ErrCommitUncertain {
+				proof.WriteEffectsUnknown = true
+			}
+		}
+	}
+	return proof, nil
+}

package/dist/templates/native-go/backend/internal/helper/cohort_publication.go

@@ -0,0 +1,18 @@
+package helper
+
+import (
+	"context"
+	"errors"
+)
+
+// Match the controller's completion-publication handoff: only a busy lock may
+// be retried, with the caller's finite budget. The transaction re-reads and
+// validates authority after acquiring policy.lock. Expiry preserves refusal.
+func retryCohortPolicy(ctx context.Context, commit func() error) error {
+	last := errBusy
+	_ = waitHealthy(ctx, func(context.Context) bool {
+		last = commit()
+		return !errors.Is(last, errBusy)
+	})
+	return last
+}

package/dist/templates/native-go/backend/internal/helper/cohort_publication_test.go

@@ -0,0 +1,105 @@
+package helper
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+)
+
+func TestCohortPolicyRetryBusyOnlyAndBounded(t *testing.T) {
+	calls := 0
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+	begin := time.Now()
+	if err := retryCohortPolicy(ctx, func() error { calls++; return errBusy }); !errors.Is(err, errBusy) {
+		t.Fatal(err)
+	}
+	if calls < 2 || time.Since(begin) > time.Second {
+		t.Fatal("unbounded or missing busy retry", calls)
+	}
+	calls = 0
+	if err := retryCohortPolicy(context.Background(), func() error { calls++; return errTrust }); !errors.Is(err, errTrust) || calls != 1 {
+		t.Fatal("nonbusy refusal retried", err, calls)
+	}
+	calls = 0
+	if err := retryCohortPolicy(context.Background(), func() error {
+		calls++
+		if calls == 1 {
+			return errBusy
+		}
+		return nil
+	}); err != nil || calls != 2 {
+		t.Fatal(err, calls)
+	}
+}
+func TestCohortFenceRetryRevalidatesUnderPolicyLock(t *testing.T) {
+	for _, change := range []string{"release", "epoch", "inventory", "stopped"} {
+		t.Run(change, func(t *testing.T) {
+			c, _ := controlFixture(t)
+			before, _ := readRecord(c.StateDir, c.Owner)
+			lock, err := os.OpenFile(filepath.Join(c.StateDir, "policy.lock"), os.O_CREATE|os.O_RDWR, 0600)
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer lock.Close()
+			if err := syscall.Flock(int(lock.Fd()), syscall.LOCK_EX); err != nil {
+				t.Fatal(err)
+			}
+			attempted := make(chan struct{})
+			result := make(chan error, 1)
+			ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+			defer cancel()
+			go func() {
+				once := false
+				result <- retryCohortPolicy(ctx, func() error {
+					err := fenceRecord(c.Client, before.Lifecycle.Epoch, "unit-stopped")
+					if !once {
+						once = true
+						close(attempted)
+					}
+					return err
+				})
+			}()
+			<-attempted
+			r, _ := readRecord(c.StateDir, c.Owner)
+			switch change {
+			case "epoch":
+				r.Lifecycle.Epoch = strings.Repeat("e", 64)
+			case "inventory":
+				r.Inventory.Version = "9.0.0-0001"
+			case "stopped":
+				r.Lifecycle.Phase = "stopped"
+			}
+			if err := writeProtected(c.StateDir, "approval.json", r); err != nil {
+				t.Fatal(err)
+			}
+			saved, _ := os.ReadFile(filepath.Join(c.StateDir, "approval.json"))
+			if err := syscall.Flock(int(lock.Fd()), syscall.LOCK_UN); err != nil {
+				t.Fatal(err)
+			}
+			err = <-result
+			if change == "release" {
+				if err != nil {
+					t.Fatal(err)
+				}
+				current, _ := readRecord(c.StateDir, c.Owner)
+				if current.Lifecycle.Phase != "fenced" {
+					t.Fatal(current)
+				}
+			} else {
+				if !errors.Is(err, errTrust) {
+					t.Fatal("changed authority retried/accepted", err)
+				}
+				after, _ := os.ReadFile(filepath.Join(c.StateDir, "approval.json"))
+				if string(after) != string(saved) {
+					t.Fatal("changed authority overwritten")
+				}
+			}
+		})
+	}
+}