refactor(storage): split immutable context targets (#2)

* refactor(storage): split immutable context targets

* style(signer): satisfy gofumpt

* refactor(storage): make context APIs explicit

* fix(storage): restore identity, resume, and context validation

* fix(storage): validate replacements and restore coverage gates

Author: strahe

Makefile

@@ -16,9 +16,10 @@ build:
 test:
 	go test ./...
 
-# Run benchmarks — auto-discovers packages containing *_bench_test.go files
+# Run benchmarks — auto-discovers packages containing *_bench_test.go files.
+# Skip hidden dirs (worktrees, .git) and local reference checkouts.
 bench:
-	go test -bench=. -benchmem $(shell find . -name '*_bench_test.go' | sed 's|/[^/]*$$||' | sort -u)
+	go test -bench=. -benchmem $(shell find . \( -path '*/.*' -o -path './lotus' -o -path './curio' -o -path './synapse-sdk' -o -path './go-synapse' \) -prune -o -name '*_bench_test.go' -print | sed 's|/[^/]*$$||' | sort -u)
 
 # Run tests with race detector
 test-race:

README.md

@@ -7,8 +7,7 @@
 [![License](https://img.shields.io/github/license/strahe/synapse-go)](LICENSE)
 [![Go Version](https://img.shields.io/badge/go-1.26.3%2B-00ADD8)](go.mod)
 
-Go SDK for Filecoin Onchain Cloud (FOC), ported from the
-[@filoz/synapse-sdk](https://github.com/FilOzone/synapse-sdk).
+Go SDK for Filecoin Onchain Cloud (FOC).
 
 > **Status:** Beta - API may change.
 

doc.go

@@ -17,7 +17,7 @@
 //
 //	// data must contain uploadable content; PieceCIDv2 requires at least
 //	// 127 raw bytes.
-//	result, err := client.Storage().Upload(ctx, data, nil)
+//	result, err := client.Storage().Upload(ctx, data, &storage.UploadOptions{Copies: 2})
 //
 // Sub-services are accessed via getters: [Client.Storage], [Client.Payments],
 // [Client.WarmStorage], [Client.SPRegistry], [Client.Costs], [Client.FilBeam],
@@ -34,7 +34,7 @@
 // This SDK is in its 0.x phase. Public APIs may change between minor
 // releases; breaking changes are called out in release notes. Pin to a
 // specific minor version in production. The implementation tracks the
-// Filecoin Onchain Cloud protocol and the upstream TypeScript SDK.
+// Filecoin Onchain Cloud protocol.
 //
 // [piece]: https://pkg.go.dev/github.com/strahe/synapse-go/piece
 package synapse

docs/GETTING_STARTED.md

@@ -110,11 +110,9 @@ exceeding it returns `storage.ErrMaxBytesExceeded`.
 
 ## Upload Controls
 
-Use `storage.UploadOptions` when the default upload is not enough:
+`Service.Upload` performs automatic target selection. Its options include:
 
-- `Copies`: requested provider copies. Zero means the selection default.
-- `ProviderIDs`: pin copies to specific providers.
-- `DataSetIDs`: write to specific existing datasets.
+- `Copies`: required number of provider copies. It must be greater than zero.
 - `ExcludeProviderIDs`: skip providers only during automatic selection.
 - `DataSetMetadata`: metadata used when creating or reusing datasets.
 - `PieceMetadata`: metadata stored with the committed piece.
@@ -133,20 +131,40 @@ to know whether every requested copy succeeded.
 Dataset metadata must match exactly for automatic dataset reuse. Use stable
 metadata values when you want uploads to share payment rails.
 
+Use `NewProviderContext` or `NewDataSetContext` for a known target. Use
+`UploadToContexts` when the caller, rather than the SDK, must determine the
+exact providers and their primary-to-secondary order.
+
 ## Funding Preflight
 
 `Prepare` is optional. Use it before a first upload, before a large batch, or
 when your UI needs to show whether the account has enough USDFC deposit and
-FWSS approval. If `Transaction` is nil, the account is already ready for the
-requested size and contexts. Match options that affect context selection, such
-as CDN.
+FWSS approval. Select the upload targets first, then pass the same contexts to
+`Prepare` and `UploadToContexts`. This ensures the estimate and upload use the
+same providers, datasets, payer, chain, and record keeper.
 
 ```go
 withCDN := true
 
+selection, selectErr := client.Storage().SelectUploadContexts(ctx,
+    storage.SelectUploadContextsOptions{
+        Copies:  2,
+        WithCDN: &withCDN,
+        DataSetMetadata: map[string]string{
+            "project": "photos",
+        },
+    },
+)
+if selectErr != nil && !errors.Is(selectErr, storage.ErrInsufficientUploadContexts) {
+    return selectErr
+}
+if selection == nil {
+    return errors.New("no upload contexts available")
+}
+
 prep, err := client.Storage().Prepare(ctx, &storage.PrepareOptions{
-    DataSize:  uint64(payloadSize),
-    EnableCDN: &withCDN,
+    DataSize: uint64(payloadSize),
+    Contexts: selection.Contexts,
 })
 if err != nil {
     return err
@@ -159,62 +177,91 @@ if prep.Transaction != nil {
     }
     fmt.Println("prepare tx:", tx.Hash)
 }
+
+result, err := client.Storage().UploadToContexts(
+    ctx,
+    file,
+    selection.Contexts,
+    &storage.UploadOptions{
+        PieceMetadata: map[string]string{"name": "payload.bin"},
+    },
+)
+if err != nil {
+    return err
+}
 ```
 
-If you already selected contexts, pass them through `PrepareOptions.Contexts`
-so the estimate matches the exact providers and datasets. `CreateContexts`
-returns managed `*storage.Context` values; convert the slice element-by-element
-when filling the `[]storage.UploadContext` field.
+When selection finds at least one but fewer than the requested targets, it
+returns both a usable `UploadContextSelection` and an
+`InsufficientUploadContextsError`. The application can continue with the
+available contexts or stop before funding. With `UploadToContexts`, the
+selection length becomes `UploadResult.RequestedCopies` and no replacement
+provider is selected automatically.
 
 For read-only cost and account state, use `GetStorageInfo` or
 `CalculateMultiContextCosts`.
 
 ## Contexts And Datasets
 
-Use contexts when you need provider or dataset control before uploading.
+There are two immutable context types:
+
+- `ProviderContext` identifies one provider and no dataset. `Commit` and
+  `Pull` create a new dataset.
+- `DataSetContext` identifies one provider and one existing dataset. `Commit`
+  and `Pull` always target that dataset.
+
+Provider-scoped methods such as `Store` and `Download` are shared. For example,
+both `ProviderContext.Download` and `DataSetContext.Download` retrieve a piece
+from the same configured provider or CDN; the dataset binding does not change
+piece retrieval. Dataset inspection, deletion, and termination methods exist
+only on `DataSetContext`.
+
+Select one approved, active, healthy provider without looking up datasets:
 
 ```go
-contexts, err := client.Storage().CreateContexts(ctx, &storage.CreateContextsOptions{
-    Copies: 2,
-    DataSetMetadata: map[string]string{
-        "project": "photos",
+providerCtx, err := client.Storage().SelectProviderContext(ctx,
+    storage.SelectProviderContextOptions{
+        DataSetMetadata: map[string]string{
+            "project": "photos",
+        },
     },
-})
+)
 if err != nil {
     return err
 }
-
-fmt.Println("contexts:", len(contexts))
 ```
 
-```go
-prepareContexts := make([]storage.UploadContext, len(contexts))
-for i, c := range contexts {
-    prepareContexts[i] = c
-}
+Open a registered provider by ID without checking approval, activity, endpoint
+health, or existing datasets:
 
-prep, err := client.Storage().Prepare(ctx, &storage.PrepareOptions{
-    DataSize: uint64(payloadSize),
-    Contexts: prepareContexts,
-})
+```go
+providerID := types.NewBigInt(123)
+providerCtx, err := client.Storage().NewProviderContext(ctx, providerID,
+    storage.NewProviderContextOptions{
+        DataSetMetadata: map[string]string{"project": "photos"},
+    },
+)
 if err != nil {
     return err
 }
-fmt.Println("ready:", prep.Costs.Ready)
 ```
 
-For one provider or one dataset:
+Open an existing dataset owned by the current payer. The optional provider ID
+is an ownership assertion. Opening a terminated or currently unwritable
+dataset is allowed for inspection and cleanup; a later `Commit` or `Upload`
+still checks writability.
 
 ```go
 providerID := types.NewBigInt(123)
-ctx1, err := client.Storage().CreateContext(ctx, &storage.CreateContextOptions{
-    ProviderID: &providerID,
-})
+dataSetID := types.NewBigInt(456)
+dataSetCtx, err := client.Storage().NewDataSetContext(ctx, dataSetID,
+    storage.NewDataSetContextOptions{ProviderID: &providerID},
+)
 if err != nil {
     return err
 }
 
-result, err := ctx1.Upload(ctx, file, &storage.UploadOptions{
+result, err := dataSetCtx.Upload(ctx, file, &storage.UploadOptions{
     PieceMetadata: map[string]string{"name": "payload.bin"},
 })
 if err != nil {
@@ -223,65 +270,80 @@ if err != nil {
 fmt.Println(result.PieceCID)
 ```
 
-When resuming a known dataset, pass `DataSetID`. If you also pass
-`ProviderID`, the SDK checks that the dataset belongs to that provider.
+`DataSetRef` is the persistent reference for a complete provider and dataset
+target. Its zero value is invalid; construct it explicitly and use accessors to
+read IDs.
 
 ```go
-dataSetID := types.NewBigInt(456)
-providerID := types.NewBigInt(123)
-ctx1, err := client.Storage().CreateContext(ctx, &storage.CreateContextOptions{
-    DataSetID:  &dataSetID,
-    ProviderID: &providerID,
-})
+ref, err := storage.NewDataSetRef(providerID, dataSetID, dataSetCtx.ClientDataSetID())
 if err != nil {
     return err
 }
+fmt.Println("dataset:", ref.DataSetID())
 ```
 
-To create an empty dataset first, persist the submission if your process may
-restart before confirmation:
+To create an empty dataset first, persist the submission if the process may
+restart before confirmation. Creation is available only on `ProviderContext`.
 
 ```go
 var submitted storage.CreateDataSetSubmission
 
-created, err := ctx1.CreateDataSet(ctx, &storage.CreateDataSetOptions{
+created, err := providerCtx.CreateDataSet(ctx, &storage.CreateDataSetOptions{
     OnSubmitted: func(s storage.CreateDataSetSubmission) {
         submitted = s
     },
 })
 if err != nil {
     return err
 }
-fmt.Println("dataset:", created.DataSetID)
+fmt.Println("dataset:", created.DataSet.DataSetID())
 ```
 
-Resume a submitted create transaction:
+Resume a submitted create transaction with any fresh `ProviderContext` for the
+same provider, then convert the returned reference without mutating that
+context:
 
 ```go
-created, err := ctx1.WaitForDataSetCreated(ctx, submitted)
+created, err := providerCtx.WaitForDataSetCreated(ctx, submitted)
 if err != nil {
     return err
 }
-fmt.Println("dataset:", created.DataSetID)
+dataSetCtx, err := providerCtx.ForDataSet(created.DataSet)
+if err != nil {
+    return err
+}
+fmt.Println("dataset:", dataSetCtx.DataSetID())
 ```
 
-Use `GetDefaultContext` when the context resolver defaults are enough.
-Advanced callers can split a context upload into `Store`, `Pull`,
+The receiver never binds or changes target after creation. Concurrent creates
+on one `ProviderContext` are independent; adds on one `DataSetContext` may run
+in parallel. Advanced callers can split a context upload into `Store`, `Pull`,
 `PresignForCommit`, and `Commit`.
 
+### Migrating From The Previous Context API
+
+| Previous call | Replacement |
+|---------------|-------------|
+| `CreateContext(nil)` / `GetDefaultContext()` | `SelectProviderContext(...)` |
+| `CreateContext` with `ProviderID` | `NewProviderContext(...)` |
+| `CreateContext` with `DataSetID` | `NewDataSetContext(...)` |
+| `CreateContexts` for a new upload | `SelectUploadContexts(...)` |
+| `Upload` with provider or dataset IDs | construct/select contexts, then call `UploadToContexts(...)` |
+| `Prepare` without contexts | select contexts first and pass the same slice to `Prepare` |
+
 ## Discovery And Lifecycle
 
 Common management calls:
 
 - `FindDataSets`: list datasets owned by the signer or another payer.
 - `GetStorageInfo`: inspect providers, pricing, limits, and allowances.
-- `Context.Download`: download from a known provider and dataset context.
-- `Context.DeletePieceByID`: schedule exact removal by on-chain piece ID.
-- `Context.DeletePiece`: schedule removal by piece CID convenience lookup. Prefer
+- `ProviderContext.Download` / `DataSetContext.Download`: download from a known provider.
+- `DataSetContext.DeletePieceByID`: schedule exact removal by on-chain piece ID.
+- `DataSetContext.DeletePiece`: schedule removal by piece CID convenience lookup. Prefer
   `DeletePieceByID` when available, because repeated uploads can share a CID.
-- `Context.TerminateService` / `Service.TerminateService`: terminate service
+- `DataSetContext.TerminateService` / `Service.TerminateService`: terminate service
   through the provider by default; use `SkipProvider` for direct FWSS fallback.
-- `Context.Terminate` / `Service.TerminateDataSet`: legacy direct FWSS
+- `DataSetContext.Terminate` / `Service.TerminateDataSet`: legacy direct FWSS
   termination write.
 
 Termination and removal are storage lifecycle actions. Treat them as

examples/quickstart/main.go

@@ -28,6 +28,7 @@ import (
 )
 
 const (
+	quickstartCopies             = 2
 	quickstartSource             = "synapse-go-quickstart"
 	quickstartDownloadAttempts   = 5
 	quickstartDownloadRetryDelay = 30 * time.Second
@@ -117,7 +118,18 @@ func runQuickstart(ctx context.Context, cfg quickstartConfig, svc quickstartStor
 		return err
 	}
 
-	prepare, err := svc.Prepare(ctx, &storage.PrepareOptions{DataSize: uint64(len(cfg.Payload))})
+	selection, err := svc.SelectUploadContexts(ctx, storage.SelectUploadContextsOptions{Copies: quickstartCopies})
+	if err != nil && !errors.Is(err, storage.ErrInsufficientUploadContexts) {
+		return fmt.Errorf("select upload contexts: %w", err)
+	}
+	if selection == nil {
+		return errors.New("select upload contexts: no selection returned")
+	}
+
+	prepare, err := svc.Prepare(ctx, &storage.PrepareOptions{
+		DataSize: uint64(len(cfg.Payload)),
+		Contexts: selection.Contexts,
+	})
 	if err != nil {
 		return fmt.Errorf("prepare upload: %w", err)
 	}
@@ -134,7 +146,7 @@ func runQuickstart(ctx context.Context, cfg quickstartConfig, svc quickstartStor
 		}
 	}
 
-	upload, err := svc.Upload(ctx, bytes.NewReader(cfg.Payload), nil)
+	upload, err := svc.UploadToContexts(ctx, bytes.NewReader(cfg.Payload), selection.Contexts, nil)
 	if err != nil {
 		return fmt.Errorf("upload: %w", err)
 	}
@@ -156,8 +168,9 @@ func runQuickstart(ctx context.Context, cfg quickstartConfig, svc quickstartStor
 }
 
 type quickstartStorage interface {
+	SelectUploadContexts(context.Context, storage.SelectUploadContextsOptions) (*storage.UploadContextSelection, error)
 	Prepare(context.Context, *storage.PrepareOptions) (*storage.PrepareResult, error)
-	Upload(context.Context, io.Reader, *storage.UploadOptions) (*storage.UploadResult, error)
+	UploadToContexts(context.Context, io.Reader, []storage.StorageContext, *storage.UploadOptions) (*storage.UploadResult, error)
 	Download(context.Context, cid.Cid, *storage.DownloadOptions) (io.ReadCloser, error)
 }
 
@@ -169,8 +182,12 @@ func (w storageWorkflow) Prepare(ctx context.Context, opts *storage.PrepareOptio
 	return w.svc.Prepare(ctx, opts)
 }
 
-func (w storageWorkflow) Upload(ctx context.Context, r io.Reader, opts *storage.UploadOptions) (*storage.UploadResult, error) {
-	return w.svc.Upload(ctx, r, opts)
+func (w storageWorkflow) SelectUploadContexts(ctx context.Context, opts storage.SelectUploadContextsOptions) (*storage.UploadContextSelection, error) {
+	return w.svc.SelectUploadContexts(ctx, opts)
+}
+
+func (w storageWorkflow) UploadToContexts(ctx context.Context, r io.Reader, contexts []storage.StorageContext, opts *storage.UploadOptions) (*storage.UploadResult, error) {
+	return w.svc.UploadToContexts(ctx, r, contexts, opts)
 }
 
 func (w storageWorkflow) Download(ctx context.Context, pieceCID cid.Cid, opts *storage.DownloadOptions) (io.ReadCloser, error) {