G0 D2: storaged S3 GET/PUT/LIST/DELETE · 3-lineage scrum · 4 fixes applied

Phase G0 Day 2 ships storaged: aws-sdk-go-v2 wrapper + chi routes
binding 127.0.0.1:3211 with 256 MiB MaxBytesReader, Content-Length
up-front 413, and a 4-slot non-blocking semaphore returning 503 +
Retry-After:5 when full. Acceptance smoke (6/6 probes) PASSES against
the dedicated MinIO bucket lakehouse-go-primary, isolated from the
Rust system's lakehouse bucket during coexistence.

Cross-lineage scrum on the shipped code:
  - Opus 4.7 (opencode): 1 BLOCK + 3 WARN + 3 INFO
  - Qwen3-coder (openrouter): 2 BLOCK + 1 WARN + 1 INFO (3 false positives)
  - Kimi K2-0905 (openrouter, after route-shopping past opencode's 4k
    cap and the direct adapter's empty-content reasoning bug):
    1 BLOCK + 2 WARN + 1 INFO

Fixed:
  C1 buildRegistry ctx cancel footgun → context.Background()
     (Opus + Kimi convergent; future credential refresh chains)
  C2 MaxBytesReader unwrap through manager.Uploader multipart
     goroutines → Content-Length up-front 413 + string-suffix fallback
     (Opus + Kimi convergent; latent 500-instead-of-413 in 5-256 MiB range)
  C3 Bucket.List unbounded accumulation → MaxListResults=10_000 cap
     (Opus + Kimi convergent; OOM guard)
  S1 PUT response Content-Type: application/json (Opus single-reviewer)

Strict validateKey policy (J approved): rejects empty, >1024B, NUL,
leading "/", ".." path components, CR/LF/tab control characters.
DELETE exposed at HTTP layer (J approved option A) for symmetry +
smoke ergonomics.

Build clean, vet clean, all unit tests pass, smoke 6/6 PASS after
every fix round. go.mod 1.23 → 1.24 (required by aws-sdk-go-v2).

Process finding worth recording: opencode caps non-streaming Kimi at
max_tokens=4096; the direct kimi.com adapter consumed 8192 tokens of
reasoning but surfaced empty content; openrouter/moonshotai/kimi-k2-0905
delivered structured output in ~33s. Future Kimi scrums should default
to that route.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

internal/secrets/provider.go

@@ -0,0 +1,108 @@
+// Package secrets resolves credentials for storaged + future bucket
+// federation (G2). The G0 surface is one method — S3Credentials —
+// looked up by logical bucket name. Multi-bucket lands in G2; until
+// then every lookup returns the same credentials, but callers already
+// pass the name so the API doesn't need to change later.
+//
+// FileProvider reads /etc/lakehouse/secrets.toml. If that file is
+// absent OR doesn't contain credentials for the requested bucket, the
+// provider falls back to the values supplied via the inline config
+// (lakehouse.toml [s3] block). G0 is dev-only so the inline fallback
+// is convenient; G1 will tighten this to "secrets file required".
+package secrets
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"sync"
+
+	"github.com/pelletier/go-toml/v2"
+)
+
+// S3Credentials is what storaged hands to aws-sdk-go-v2 to sign
+// requests. Region/endpoint/bucket are config (non-secret) and live
+// on shared.S3Config — those don't pass through this provider.
+type S3Credentials struct {
+	AccessKeyID     string `toml:"access_key_id"`
+	SecretAccessKey string `toml:"secret_access_key"`
+}
+
+// Provider is the interface storaged depends on. Keeping this small
+// is deliberate — every method here is a future migration point when
+// secrets move to Vault / SOPS / SSM.
+type Provider interface {
+	S3Credentials(bucket string) (S3Credentials, error)
+}
+
+// FileProvider is the G0 implementation. It loads the file once on
+// construction; reload-on-SIGHUP is a G1 concern.
+type FileProvider struct {
+	path     string
+	parsed   secretsFile
+	fallback S3Credentials
+	mu       sync.RWMutex
+}
+
+// secretsFile mirrors the on-disk TOML shape:
+//
+//   [s3.primary]
+//   access_key_id = "..."
+//   secret_access_key = "..."
+//
+//   [s3.archive]   # G2 multi-bucket
+//   access_key_id = "..."
+type secretsFile struct {
+	S3 map[string]S3Credentials `toml:"s3"`
+}
+
+// NewFileProvider loads `path`. If the file is missing the provider
+// is still usable with the inline fallback — that's a deliberate
+// G0 affordance. Any other read/parse error is fatal.
+func NewFileProvider(path string, fallback S3Credentials) (*FileProvider, error) {
+	p := &FileProvider{path: path, fallback: fallback}
+	b, err := os.ReadFile(path)
+	if errors.Is(err, fs.ErrNotExist) {
+		return p, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("read secrets %q: %w", path, err)
+	}
+	if err := toml.Unmarshal(b, &p.parsed); err != nil {
+		return nil, fmt.Errorf("parse secrets %q: %w", path, err)
+	}
+	return p, nil
+}
+
+// S3Credentials resolves bucket → credentials. Lookup order:
+//   1. secrets file [s3.<bucket>] section
+//   2. inline fallback (lakehouse.toml [s3])
+//
+// If neither produces a non-empty AccessKeyID, returns an error so a
+// misconfigured deployment fails loud instead of trying anonymous S3.
+func (p *FileProvider) S3Credentials(bucket string) (S3Credentials, error) {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+
+	if creds, ok := p.parsed.S3[bucket]; ok && creds.AccessKeyID != "" {
+		return creds, nil
+	}
+	if p.fallback.AccessKeyID != "" {
+		return p.fallback, nil
+	}
+	return S3Credentials{}, fmt.Errorf("no credentials for bucket %q (file=%q)", bucket, p.path)
+}
+
+// StaticProvider is a test/dev helper that returns the same creds for
+// every bucket. Use NewFileProvider in production code paths.
+type StaticProvider struct {
+	Creds S3Credentials
+}
+
+func (p StaticProvider) S3Credentials(_ string) (S3Credentials, error) {
+	if p.Creds.AccessKeyID == "" {
+		return S3Credentials{}, errors.New("StaticProvider: no AccessKeyID")
+	}
+	return p.Creds, nil
+}

internal/secrets/provider_test.go

@@ -0,0 +1,122 @@
+package secrets
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestFileProvider_ParsesSection(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "secrets.toml")
+	if err := os.WriteFile(path, []byte(`
+[s3.primary]
+access_key_id     = "AK"
+secret_access_key = "SK"
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	p, err := NewFileProvider(path, S3Credentials{})
+	if err != nil {
+		t.Fatalf("NewFileProvider: %v", err)
+	}
+	got, err := p.S3Credentials("primary")
+	if err != nil {
+		t.Fatalf("S3Credentials: %v", err)
+	}
+	if got.AccessKeyID != "AK" || got.SecretAccessKey != "SK" {
+		t.Errorf("got %+v, want {AK, SK}", got)
+	}
+}
+
+func TestFileProvider_FallbackWhenSectionMissing(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "secrets.toml")
+	// File exists, but doesn't have an [s3.primary] block.
+	if err := os.WriteFile(path, []byte(`
+[s3.archive]
+access_key_id     = "OTHER"
+secret_access_key = "OTHER_SK"
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	p, err := NewFileProvider(path, S3Credentials{
+		AccessKeyID:     "FALLBACK",
+		SecretAccessKey: "FALLBACK_SK",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, err := p.S3Credentials("primary")
+	if err != nil {
+		t.Fatalf("S3Credentials: %v", err)
+	}
+	if got.AccessKeyID != "FALLBACK" {
+		t.Errorf("expected fallback, got %+v", got)
+	}
+}
+
+func TestFileProvider_MissingFileIsOK(t *testing.T) {
+	p, err := NewFileProvider("/no/such/path", S3Credentials{
+		AccessKeyID:     "FALLBACK",
+		SecretAccessKey: "FALLBACK_SK",
+	})
+	if err != nil {
+		t.Fatalf("NewFileProvider should not error on missing file: %v", err)
+	}
+	got, err := p.S3Credentials("primary")
+	if err != nil {
+		t.Fatalf("S3Credentials: %v", err)
+	}
+	if got.AccessKeyID != "FALLBACK" {
+		t.Errorf("expected fallback, got %+v", got)
+	}
+}
+
+func TestFileProvider_NoCredsAtAll(t *testing.T) {
+	p, err := NewFileProvider("/no/such/path", S3Credentials{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := p.S3Credentials("primary"); err == nil {
+		t.Fatal("expected error when no creds in file or fallback")
+	}
+}
+
+func TestFileProvider_ParseError(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "bad.toml")
+	if err := os.WriteFile(path, []byte("not valid toml ===\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := NewFileProvider(path, S3Credentials{}); err == nil {
+		t.Fatal("expected parse error")
+	}
+}
+
+func TestStaticProvider(t *testing.T) {
+	p := StaticProvider{Creds: S3Credentials{AccessKeyID: "X", SecretAccessKey: "Y"}}
+	got, err := p.S3Credentials("any-bucket")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.AccessKeyID != "X" {
+		t.Errorf("got %+v", got)
+	}
+
+	empty := StaticProvider{}
+	if _, err := empty.S3Credentials("any"); err == nil {
+		t.Error("expected error from empty StaticProvider")
+	}
+}
+
+func TestStaticProvider_ErrorIsExported(t *testing.T) {
+	// Sanity: the empty-creds path should be a real error type, not nil.
+	_, err := StaticProvider{}.S3Credentials("x")
+	if err == nil || !errors.Is(err, err) {
+		t.Fatal("expected non-nil error")
+	}
+}

internal/storaged/bucket.go

@@ -0,0 +1,208 @@
+// Package storaged is the object I/O layer for Lakehouse-Go. Bucket
+// wraps aws-sdk-go-v2's s3.Client + s3 manager.Uploader and exposes
+// the four operations the rest of the system actually needs:
+// Get, Put, List, Delete. Path-style addressing is forced on for
+// MinIO; AWS deployments override it via shared.S3Config.UsePathStyle.
+package storaged
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"time"
+
+	"github.com/aws/aws-sdk-go-v2/aws"
+	awsconfig "github.com/aws/aws-sdk-go-v2/config"
+	"github.com/aws/aws-sdk-go-v2/credentials"
+	"github.com/aws/aws-sdk-go-v2/feature/s3/manager"
+	"github.com/aws/aws-sdk-go-v2/service/s3"
+	"github.com/aws/aws-sdk-go-v2/service/s3/types"
+	"github.com/aws/smithy-go"
+
+	"git.agentview.dev/profit/golangLAKEHOUSE/internal/secrets"
+	"git.agentview.dev/profit/golangLAKEHOUSE/internal/shared"
+)
+
+// ErrKeyNotFound is returned by Get/Delete when the underlying S3
+// response is NoSuchKey or 404. Callers translate it to HTTP 404.
+var ErrKeyNotFound = errors.New("storaged: key not found")
+
+// ObjectInfo is the per-key data List returns. We don't surface the
+// full s3.Object — most fields are noise for a single-bucket G0.
+type ObjectInfo struct {
+	Key          string
+	Size         int64
+	ETag         string
+	LastModified time.Time
+}
+
+// Bucket is the runtime handle over one S3 bucket. The logical name
+// is what callers reference (e.g. "primary"); the physical bucket on
+// the server is held in s3Bucket.
+type Bucket struct {
+	name     string
+	s3Bucket string
+	client   *s3.Client
+	uploader *manager.Uploader
+}
+
+// NewBucket builds a Bucket from the shared S3 config + a credentials
+// lookup against the provider. Region/endpoint/path-style come from
+// the inline config; access keys come from the provider so they can
+// migrate to Vault / SSM later without a config schema change.
+func NewBucket(ctx context.Context, cfg shared.S3Config, prov secrets.Provider, logicalName string) (*Bucket, error) {
+	creds, err := prov.S3Credentials(logicalName)
+	if err != nil {
+		return nil, err
+	}
+
+	awsCfg, err := awsconfig.LoadDefaultConfig(ctx,
+		awsconfig.WithRegion(cfg.Region),
+		awsconfig.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(
+			creds.AccessKeyID, creds.SecretAccessKey, "",
+		)),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("aws config: %w", err)
+	}
+
+	client := s3.NewFromConfig(awsCfg, func(o *s3.Options) {
+		if cfg.Endpoint != "" {
+			o.BaseEndpoint = aws.String(cfg.Endpoint)
+		}
+		o.UsePathStyle = cfg.UsePathStyle
+	})
+
+	return &Bucket{
+		name:     logicalName,
+		s3Bucket: cfg.Bucket,
+		client:   client,
+		uploader: manager.NewUploader(client),
+	}, nil
+}
+
+// Name returns the logical name (e.g. "primary"). Useful for logs.
+func (b *Bucket) Name() string { return b.name }
+
+// Get streams an object back to the caller. The returned ReadCloser
+// must be closed; on ErrKeyNotFound it is nil.
+func (b *Bucket) Get(ctx context.Context, key string) (io.ReadCloser, *ObjectInfo, error) {
+	out, err := b.client.GetObject(ctx, &s3.GetObjectInput{
+		Bucket: aws.String(b.s3Bucket),
+		Key:    aws.String(key),
+	})
+	if err != nil {
+		if isNotFound(err) {
+			return nil, nil, ErrKeyNotFound
+		}
+		return nil, nil, fmt.Errorf("s3 get %q: %w", key, err)
+	}
+	info := &ObjectInfo{
+		Key: key,
+	}
+	if out.ContentLength != nil {
+		info.Size = *out.ContentLength
+	}
+	if out.ETag != nil {
+		info.ETag = *out.ETag
+	}
+	if out.LastModified != nil {
+		info.LastModified = *out.LastModified
+	}
+	return out.Body, info, nil
+}
+
+// Put uploads via the s3 manager.Uploader so bodies above the SDK's
+// part threshold (~5 MiB) auto-multipart without buffering. Caller
+// is responsible for capping body size before calling — Bucket itself
+// is a thin pipe; the 256 MiB MaxBytesReader gate lives in cmd/storaged.
+func (b *Bucket) Put(ctx context.Context, key string, body io.Reader) error {
+	_, err := b.uploader.Upload(ctx, &s3.PutObjectInput{
+		Bucket: aws.String(b.s3Bucket),
+		Key:    aws.String(key),
+		Body:   body,
+	})
+	if err != nil {
+		return fmt.Errorf("s3 put %q: %w", key, err)
+	}
+	return nil
+}
+
+// MaxListResults caps a single List call so a stray prefix="" against
+// a large bucket can't OOM the daemon. Per Opus + Kimi convergent
+// scrum review (D2 round). G2 multi-bucket federation will introduce
+// continuation tokens so callers can paginate explicitly.
+const MaxListResults = 10_000
+
+// List returns up to MaxListResults objects whose key starts with
+// prefix. If the bucket holds more than the cap, the result is
+// truncated and a sentinel ObjectInfo with Key="...truncated..." is
+// appended so callers see they didn't get everything. G0 single-bucket
+// dev workloads are far below the cap; the cap protects against
+// production bucket sizes during the migration.
+func (b *Bucket) List(ctx context.Context, prefix string) ([]ObjectInfo, error) {
+	out := make([]ObjectInfo, 0, 64)
+	pager := s3.NewListObjectsV2Paginator(b.client, &s3.ListObjectsV2Input{
+		Bucket: aws.String(b.s3Bucket),
+		Prefix: aws.String(prefix),
+	})
+	for pager.HasMorePages() {
+		page, err := pager.NextPage(ctx)
+		if err != nil {
+			return nil, fmt.Errorf("s3 list prefix=%q: %w", prefix, err)
+		}
+		for _, o := range page.Contents {
+			if len(out) >= MaxListResults {
+				out = append(out, ObjectInfo{Key: "...truncated..."})
+				return out, nil
+			}
+			oi := ObjectInfo{}
+			if o.Key != nil {
+				oi.Key = *o.Key
+			}
+			if o.Size != nil {
+				oi.Size = *o.Size
+			}
+			if o.ETag != nil {
+				oi.ETag = *o.ETag
+			}
+			if o.LastModified != nil {
+				oi.LastModified = *o.LastModified
+			}
+			out = append(out, oi)
+		}
+	}
+	return out, nil
+}
+
+// Delete removes one object. Idempotent: deleting a missing key is
+// not an error on S3, so we don't translate that to ErrKeyNotFound.
+func (b *Bucket) Delete(ctx context.Context, key string) error {
+	_, err := b.client.DeleteObject(ctx, &s3.DeleteObjectInput{
+		Bucket: aws.String(b.s3Bucket),
+		Key:    aws.String(key),
+	})
+	if err != nil {
+		return fmt.Errorf("s3 delete %q: %w", key, err)
+	}
+	return nil
+}
+
+// isNotFound checks both the typed s3 NoSuchKey error and the smithy
+// generic 404 — different code paths in the SDK surface different
+// shapes depending on whether HEAD-then-GET happens.
+func isNotFound(err error) bool {
+	var nsk *types.NoSuchKey
+	if errors.As(err, &nsk) {
+		return true
+	}
+	var apiErr smithy.APIError
+	if errors.As(err, &apiErr) {
+		switch apiErr.ErrorCode() {
+		case "NoSuchKey", "NotFound":
+			return true
+		}
+	}
+	return false
+}

internal/storaged/registry.go

@@ -0,0 +1,64 @@
+// BucketRegistry resolves logical bucket names → *Bucket. G0 holds
+// exactly one bucket ("primary"); G2 (multi-bucket federation, per
+// Rust ADR-017) extends this to many. Keeping the registry as a
+// distinct type now means cmd/storaged never has to be refactored
+// when G2 lands — every handler already routes through Resolve.
+package storaged
+
+import (
+	"errors"
+	"fmt"
+	"sync"
+)
+
+var ErrBucketUnknown = errors.New("storaged: unknown bucket")
+
+// BucketRegistry is a thread-safe map of logical name → *Bucket.
+// In G0 only "primary" is registered; the registry exists so that
+// when G2 multi-bucket lands we add buckets in registry.go and the
+// HTTP layer is unchanged.
+type BucketRegistry struct {
+	mu      sync.RWMutex
+	buckets map[string]*Bucket
+}
+
+func NewRegistry() *BucketRegistry {
+	return &BucketRegistry{buckets: make(map[string]*Bucket)}
+}
+
+// Register adds a bucket under its logical name. Re-registering the
+// same name is rejected — G0 services build the registry once at
+// startup and a duplicate is almost always a config bug.
+func (r *BucketRegistry) Register(b *Bucket) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if _, exists := r.buckets[b.name]; exists {
+		return fmt.Errorf("bucket %q already registered", b.name)
+	}
+	r.buckets[b.name] = b
+	return nil
+}
+
+// Resolve returns the bucket for a logical name. G0 callers pass
+// "primary" since that's the only one registered.
+func (r *BucketRegistry) Resolve(name string) (*Bucket, error) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	b, ok := r.buckets[name]
+	if !ok {
+		return nil, fmt.Errorf("%w: %q", ErrBucketUnknown, name)
+	}
+	return b, nil
+}
+
+// Names returns the registered logical names (sorted-order not
+// guaranteed). Useful for /health surface or debug dumps.
+func (r *BucketRegistry) Names() []string {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	out := make([]string, 0, len(r.buckets))
+	for name := range r.buckets {
+		out = append(out, name)
+	}
+	return out
+}

internal/storaged/registry_test.go

@@ -0,0 +1,49 @@
+package storaged
+
+import (
+	"errors"
+	"testing"
+)
+
+func TestRegistry_RegisterAndResolve(t *testing.T) {
+	r := NewRegistry()
+	b := &Bucket{name: "primary"}
+	if err := r.Register(b); err != nil {
+		t.Fatalf("Register: %v", err)
+	}
+	got, err := r.Resolve("primary")
+	if err != nil {
+		t.Fatalf("Resolve: %v", err)
+	}
+	if got != b {
+		t.Errorf("Resolve returned different bucket")
+	}
+}
+
+func TestRegistry_DuplicateRegisterRejected(t *testing.T) {
+	r := NewRegistry()
+	if err := r.Register(&Bucket{name: "primary"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := r.Register(&Bucket{name: "primary"}); err == nil {
+		t.Fatal("expected error on duplicate register")
+	}
+}
+
+func TestRegistry_UnknownReturnsErrBucketUnknown(t *testing.T) {
+	r := NewRegistry()
+	_, err := r.Resolve("nope")
+	if !errors.Is(err, ErrBucketUnknown) {
+		t.Fatalf("expected ErrBucketUnknown, got %v", err)
+	}
+}
+
+func TestRegistry_Names(t *testing.T) {
+	r := NewRegistry()
+	_ = r.Register(&Bucket{name: "primary"})
+	_ = r.Register(&Bucket{name: "archive"})
+	names := r.Names()
+	if len(names) != 2 {
+		t.Fatalf("expected 2 names, got %d", len(names))
+	}
+}