feat: allow injecting a pre-configured AWS client into pkg/snipe (#124)

Snipe always resolved its AWS client via spawnaws.NewClientWithRegion,
which loads config through the default credential chain — no way to point
it at a custom endpoint. spawnaws.Client already has NewClientFromConfig,
documented as "used in tests to point all SDK calls at an emulator such as
Substrate", but Snipe had no way to reach it: acquirer.clientFor is
unexported and Options had no field for injecting one.

Adds Options.ClientFor: an optional override for the per-region client
builder, mirroring acquirer's internal clientFor shape. Snipe still calls
it once per distinct region and caches the result for the run, exactly
like the default spawnaws.NewClientWithRegion path (which remains the zero
value behavior).

Adds pkg/snipe/snipe_substrate_test.go:
- TestSnipe_AgainstSubstrate exercises Snipe's real request-building/
  response-parsing/retry code against a Substrate-emulated EC2 endpoint,
  the test tier #113 describes losing when calque's Acquirer migrates to
  Snipe.
- TestSnipe_ClientForOverridesDefault proves ClientFor is actually
  threaded through (not merely accepted and ignored) by asserting a
  sentinel error from a fake ClientFor surfaces from Snipe.

Confirmed both new tests fail to compile without the Options.ClientFor
field (go vet: "unknown field ClientFor in struct literal") and pass with
it restored.

Fixes #113

Author: scttfrdmn

CHANGELOG.md

@@ -26,6 +26,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ordinary PR CI: one asserts `.goreleaser.yaml`'s ldflag still names the
   `cmd.Version` variable this package actually declares, the other asserts
   the release workflow still invokes the guard script.
+- **`pkg/snipe.Options.ClientFor` — inject a pre-configured `*spawnaws.Client`
+  builder, e.g. one pointed at a test emulator like Substrate** (#113).
+  `Snipe` previously always resolved its AWS client via
+  `spawnaws.NewClientWithRegion`, which loads config through the default AWS
+  credential chain with no way to point it at a custom endpoint — so a
+  consumer wanting to exercise `Snipe`'s real request-building/response-
+  parsing/error-classification code against a fake EC2 endpoint (as calque's
+  own `Acquirer` could, via `github.com/scttfrdmn/substrate/emulator`, before
+  migrating to `Snipe`) had no way to do so. `Options.ClientFor`, if set,
+  overrides the client-resolution function Snipe calls once per distinct
+  region (cached for the run, same as the default); a caller sets it to
+  something built via `spawnaws.NewClientFromConfig` with
+  `config.WithBaseEndpoint` pointed at an emulator. Zero value is unchanged:
+  the default AWS credential chain, same as before this field existed.
 
 ### Fixed
 - **`pkg/snipe.Result.AvailabilityZone` now reports the AZ the instance

pkg/snipe/snipe.go

@@ -153,6 +153,20 @@ type Options struct {
 	// id, in-region launch artifacts/SG/subnet, etc. Off by default; opt-in only.
 	// A terminal failure on any target still stops immediately.
 	Fallbacks []Target
+	// ClientFor, if set, overrides how Snipe resolves the *spawnaws.Client for a
+	// given region — the same shape as acquirer's internal clientFor (#113). By
+	// default Snipe builds one via spawnaws.NewClientWithRegion, which loads AWS
+	// config through the default credential chain with no way to point it at a
+	// custom endpoint. A caller that wants Snipe's real request-building/
+	// response-parsing/error-classification code exercised against a fake EC2
+	// endpoint (e.g. github.com/scttfrdmn/substrate/emulator) sets ClientFor to
+	// something built via spawnaws.NewClientFromConfig with
+	// config.WithBaseEndpoint pointed at that endpoint — mirroring
+	// NewClientFromConfig's own doc comment ("Used in tests to point all SDK
+	// calls at an emulator such as Substrate"), which pkg/snipe had no way to
+	// reach before this field existed. Snipe still calls this once per distinct
+	// region and caches the result for the run, exactly like the default.
+	ClientFor func(ctx context.Context, region string) (*spawnaws.Client, error)
 }
 
 // Result is what Snipe returns on success — the launched instance's identity
@@ -188,21 +202,31 @@ type acquirer struct {
 	sleep     func(ctx context.Context, d time.Duration) error
 }
 
-func newAcquirer() *acquirer {
-	return &acquirer{clientFor: cachedClientFor(), provide: launcher.Provision, sleep: sleepCtx}
+// newAcquirer builds an *acquirer using build to construct a client for each
+// distinct region on first use, cached for the rest of the run — a
+// multi-region Snipe (Options.Fallbacks) can revisit the same region many
+// times across retry rounds. build defaults to spawnaws.NewClientWithRegion
+// (the real-AWS default-credential-chain path); a caller-supplied
+// Options.ClientFor (#113) is threaded in here instead, so a test can point
+// every client this acquirer ever builds at an emulator such as Substrate.
+func newAcquirer(build func(ctx context.Context, region string) (*spawnaws.Client, error)) *acquirer {
+	if build == nil {
+		build = spawnaws.NewClientWithRegion
+	}
+	return &acquirer{clientFor: cachedClientFor(build), provide: launcher.Provision, sleep: sleepCtx}
 }
 
-// cachedClientFor returns a clientFor function that builds one
-// region-pinned *spawnaws.Client per distinct region on first use and reuses
-// it for the rest of the run — a multi-region Snipe (Options.Fallbacks) can
-// revisit the same region many times across retry rounds.
-func cachedClientFor() func(ctx context.Context, region string) (*spawnaws.Client, error) {
+// cachedClientFor wraps build so it is called at most once per distinct
+// region for the lifetime of the returned function, regardless of how many
+// times a multi-round, possibly-multi-region (Options.Fallbacks) Snipe run
+// asks for it.
+func cachedClientFor(build func(ctx context.Context, region string) (*spawnaws.Client, error)) func(ctx context.Context, region string) (*spawnaws.Client, error) {
 	clients := make(map[string]*spawnaws.Client)
 	return func(ctx context.Context, region string) (*spawnaws.Client, error) {
 		if c, ok := clients[region]; ok {
 			return c, nil
 		}
-		c, err := spawnaws.NewClientWithRegion(ctx, region)
+		c, err := build(ctx, region)
 		if err != nil {
 			return nil, err
 		}
@@ -227,7 +251,7 @@ func cachedClientFor() func(ctx context.Context, region string) (*spawnaws.Clien
 // wait. On success it returns a *Result carrying the launched InstanceID,
 // Region, AZ, and Subnet.
 func Snipe(ctx context.Context, target Target, opts Options) (*Result, error) {
-	return snipeWith(ctx, newAcquirer(), target, opts)
+	return snipeWith(ctx, newAcquirer(opts.ClientFor), target, opts)
 }
 
 func snipeWith(ctx context.Context, l *acquirer, target Target, opts Options) (*Result, error) {

pkg/snipe/snipe_substrate_test.go

@@ -0,0 +1,101 @@
+package snipe_test
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	awssdk "github.com/aws/aws-sdk-go-v2/aws"
+	"github.com/aws/aws-sdk-go-v2/service/ssm"
+	ssmtypes "github.com/aws/aws-sdk-go-v2/service/ssm/types"
+	"github.com/spore-host/lagotto/pkg/snipe"
+	"github.com/spore-host/lagotto/pkg/testutil"
+	spawnaws "github.com/spore-host/spawn/pkg/aws"
+)
+
+// TestSnipe_AgainstSubstrate is the #113 regression guard: it exercises
+// Snipe's REAL request-building/response-parsing/retry code against a fake
+// EC2-shaped endpoint (github.com/scttfrdmn/substrate/emulator), rather than
+// a hand-rolled fake `provide` function. Before Options.ClientFor existed,
+// Snipe always built its client via spawnaws.NewClientWithRegion — the
+// default AWS credential chain, with no way to point it at Substrate's
+// in-process test server — so this test tier was impossible for pkg/snipe
+// (see #113: this is exactly the tier calque's own Acquirer had, via
+// substrate_test.go, before migrating to Snipe).
+//
+// Mirrors the skip pattern already used for the equivalent spawn/pkg/launcher
+// test (TestProvision_EndToEnd): Substrate may not fully model IAM CreateRole
+// or RunInstances, so a failure naming those is a skip, not a failure.
+func TestSnipe_AgainstSubstrate(t *testing.T) {
+	env := testutil.SubstrateServer(t)
+	ctx := context.Background()
+
+	// Seed the SSM AMI parameters spawn's launcher reads for AMI auto-detection.
+	ssmClient := ssm.NewFromConfig(env.AWSConfig)
+	for name, val := range map[string]string{
+		"/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64": "ami-x86-standard",
+		"/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-arm64":  "ami-arm-standard",
+	} {
+		if _, err := ssmClient.PutParameter(ctx, &ssm.PutParameterInput{
+			Name: awssdk.String(name), Value: awssdk.String(val), Type: ssmtypes.ParameterTypeString,
+		}); err != nil {
+			t.Skipf("substrate SSM PutParameter unavailable: %v", err)
+		}
+	}
+
+	target := snipe.Target{
+		InstanceType: "m7i.large",
+		Region:       "us-east-1",
+	}
+	opts := snipe.Options{
+		// The whole point: point every client Snipe builds at Substrate's
+		// in-process server instead of the real AWS default credential chain.
+		ClientFor: func(context.Context, string) (*spawnaws.Client, error) {
+			return spawnaws.NewClientFromConfig(env.AWSConfig), nil
+		},
+	}
+
+	result, err := snipe.Snipe(ctx, target, opts)
+	if err != nil {
+		if strings.Contains(err.Error(), "IAM") || strings.Contains(err.Error(), "launch") {
+			t.Skipf("substrate does not fully model the launch path: %v", err)
+		}
+		t.Fatalf("Snipe: %v", err)
+	}
+	if result.InstanceID == "" {
+		t.Error("Snipe returned empty InstanceID")
+	}
+	if result.Region != "us-east-1" {
+		t.Errorf("Region = %q, want us-east-1", result.Region)
+	}
+}
+
+// TestSnipe_ClientForOverridesDefault verifies ClientFor is actually used
+// (not just accepted and ignored): a ClientFor that returns a recognizable
+// error must be the one Snipe surfaces, proving Snipe called it rather than
+// falling back to spawnaws.NewClientWithRegion's real-AWS default chain.
+func TestSnipe_ClientForOverridesDefault(t *testing.T) {
+	wantErr := "sentinel-clientfor-error"
+	opts := snipe.Options{
+		ClientFor: func(context.Context, string) (*spawnaws.Client, error) {
+			return nil, errSentinel{wantErr}
+		},
+		// A ClientFor error isn't a smithy API error, so it classifies as
+		// FailureUnknown and would otherwise retry (with real sleeps) up to
+		// MaxConsecutiveUnknown times before giving up. Cap at 1 attempt and
+		// use a near-zero interval so this test asserts the error, not the
+		// retry/backoff behavior (already covered elsewhere).
+		MaxConsecutiveUnknown: 1,
+	}
+	_, err := snipe.Snipe(context.Background(), snipe.Target{
+		InstanceType: "m7i.large",
+		Region:       "us-east-1",
+	}, opts)
+	if err == nil || !strings.Contains(err.Error(), wantErr) {
+		t.Errorf("Snipe error = %v, want it to contain %q (proving ClientFor was actually called)", err, wantErr)
+	}
+}
+
+type errSentinel struct{ msg string }
+
+func (e errSentinel) Error() string { return e.msg }