ref: 5c4e61830242a3a25e332bf623adb2eb65037f2b
parent: afd58b4e5882402d606728e4f2ee8e5cb2354939
author: Runxi Yu <runxiyu@umich.edu>
date: Sun Mar 22 19:34:38 EDT 2026
receivepack/service: Clarify ownership and requirements
--- a/receivepack/service/doc.go
+++ b/receivepack/service/doc.go
@@ -1,2 +1,6 @@
// Package service implements the protocol-independent receive-pack service.
+//
+// A Service borrows the stores, roots, hooks, and I/O endpoints supplied in
+// Options. Callers retain ownership of those dependencies and must keep them
+// valid for each Execute call that uses them.
package service
--- a/receivepack/service/hook.go
+++ b/receivepack/service/hook.go
@@ -25,6 +25,10 @@
Message string
}
+// HookRequest is the borrowed view passed to one Hook invocation.
+//
+// Refs, ExistingObjects, and QuarantinedObjects are borrowed and are only
+// valid for the duration of the hook call.
type HookRequest struct {Refs refstore.ReadingStore
ExistingObjects objectstore.Store
@@ -34,4 +38,8 @@
IO HookIO
}
+// Hook is an optional per-request validation hook.
+//
+// Hook borrows the data and stores in HookRequest only for the duration of the
+// call.
type Hook func(context.Context, HookRequest) ([]UpdateDecision, error)
--- a/receivepack/service/options.go
+++ b/receivepack/service/options.go
@@ -16,6 +16,13 @@
}
// Options configures one protocol-independent receive-pack service.
+//
+// Service borrows all configured dependencies.
+//
+// Refs and ExistingObjects are required and must be non-nil.
+// ObjectsRoot is required if Execute may need to ingest or promote a pack.
+// Progress, ProgressFlush, Hook, and HookIO are optional; when provided they
+// are also borrowed for the duration of Execute.
type Options struct {Algorithm objectid.Algorithm
Refs refstore.ReadWriteStore
--- a/receivepack/service/request.go
+++ b/receivepack/service/request.go
@@ -3,6 +3,9 @@
import "io"
// Request is one protocol-independent receive-pack execution request.
+//
+// If PackExpected is true, Pack must be non-nil and remain valid until
+// Execute finishes consuming it.
type Request struct {Commands []Command
PushOptions []string
--- a/receivepack/service/service.go
+++ b/receivepack/service/service.go
@@ -1,11 +1,16 @@
package service
// Service executes protocol-independent receive-pack requests.
+//
+// Service borrows all dependencies supplied in Options.
type Service struct {opts Options
}
// New creates one receive-pack service.
+//
+// The returned service borrows opts and does not take ownership of any stores,
+// roots, hooks, or I/O endpoints reachable through it.
func New(opts Options) *Service { return &Service{opts: opts}}
--
⑨