receivepack/service: Clarify ownership and requirements

5 files changed, 27 insertions, 0 deletions

diff --git a/receivepack/service/doc.go b/receivepack/service/doc.go
index 2bb15a38..37be23f4 100644
--- 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
diff --git a/receivepack/service/hook.go b/receivepack/service/hook.go
index 748a00b9..b80d52d6 100644
--- a/receivepack/service/hook.go
+++ b/receivepack/service/hook.go
@@ -25,6 +25,10 @@ type UpdateDecision struct {
 	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 @@ type HookRequest struct {
 	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)
diff --git a/receivepack/service/options.go b/receivepack/service/options.go
index 21b84e2d..a49b6b95 100644
--- a/receivepack/service/options.go
+++ b/receivepack/service/options.go
@@ -16,6 +16,13 @@ type PromotedObjectPermissions struct {
 }
 
 // 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
diff --git a/receivepack/service/request.go b/receivepack/service/request.go
index 7a0b1f33..7f9bcc2f 100644
--- a/receivepack/service/request.go
+++ b/receivepack/service/request.go
@@ -3,6 +3,9 @@ package service
 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
diff --git a/receivepack/service/service.go b/receivepack/service/service.go
index d204e9aa..a57fd354 100644
--- 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}
 }