shithub: furgit

Info  •  Files  •  Log  •  Branches

receivepack: Lifecycle/ownership docs

--- a/receivepack/hook.go

+++ b/receivepack/hook.go

@@ -30,6 +30,9 @@

 // HookRequest is the input presented to a receive-pack hook before quarantine

 // promotion and ref updates.

+//

+// 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

@@ -43,7 +46,8 @@

 //

 // The hook runs after pack ingestion into quarantine and before quarantine

 // promotion or ref updates. The returned decisions must have the same length as

-// HookRequest.Updates.

+// HookRequest.Updates. Hook borrows the data and stores in HookRequest only for

+// the duration of the call.

 type Hook func(context.Context, HookRequest) ([]UpdateDecision, error)

 func translateHook(hook Hook) service.Hook {

--- a/receivepack/options.go

+++ b/receivepack/options.go

@@ -9,6 +9,12 @@

 )

 // Options configures one receive-pack invocation.

+//

+// ReceivePack borrows all configured dependencies.

+//

+// Refs and ExistingObjects are required and must be non-nil.

+// ObjectsRoot is required if the invocation may need to ingest or promote a

+// pack.

 type Options struct {

 	// GitProtocol is the raw Git protocol version string from the transport,

 	// such as "version=1".

@@ -27,7 +33,8 @@

 	// directories moved from quarantine into the permanent object store.

 	PromotedObjectPermissions *PromotedObjectPermissions

 	// Hook, when non-nil, runs after pack ingestion into quarantine and before

-	// quarantine promotion or ref updates.

+	// quarantine promotion or ref updates. Hook is borrowed for the duration of

+	// ReceivePack.

 	Hook Hook

 	// Agent is the receive-pack agent string advertised via capability.

 	//

--- a/receivepack/receivepack.go

+++ b/receivepack/receivepack.go

@@ -19,6 +19,9 @@

 // feels a bit ugly.

 // ReceivePack serves one receive-pack session over r/w.

+//

+// ReceivePack borrows r, w, and all dependencies reachable through opts for

+// the duration of the call. It does not close any of them.

 func ReceivePack(

 	ctx context.Context,

 	w pktline.WriteFlusher,

-- 

⑨