Add Azure Blob Storage support (M0)

README.md

@@ -690,6 +690,7 @@ Every service links to its own page with a coverage breakdown — audited operat
 | Service | Parity | PARITY Entries | Notes |
 |---|---|---|---|
 | [AppStream 2.0](services/appstream/README.md) | A | 44 | clean |
+| [Azureblob](services/azureblob/README.md) | C | 8 | 8 gaps; 2 deferred |
 | [Cloudfrontkeyvaluestore](services/cloudfrontkeyvaluestore/README.md) | B | 6 | 3 gaps; 1 structural gap |
 | [Directconnect](services/directconnect/README.md) | A | 64 | 3 gaps; 8 structural gaps; 1 deferred |
 | [Grafana](services/grafana/README.md) | A | 25 | 2 gaps; 1 structural gap |

cli.go

@@ -89,6 +89,7 @@ import (
 	athenabackend "github.com/blackbirdworks/gopherstack/services/athena"
 	autoscalingbackend "github.com/blackbirdworks/gopherstack/services/autoscaling"
 	awsconfigbackend "github.com/blackbirdworks/gopherstack/services/awsconfig"
+	azureblobbackend "github.com/blackbirdworks/gopherstack/services/azureblob"
 	backupbackend "github.com/blackbirdworks/gopherstack/services/backup"
 	batchbackend "github.com/blackbirdworks/gopherstack/services/batch"
 	bedrockbackend "github.com/blackbirdworks/gopherstack/services/bedrock"
@@ -458,6 +459,7 @@ type CLI struct {
 	Kinesis                       kinesisbackend.Settings   `embed:"" prefix:"kinesis-"`
 	STS                           stsbackend.Settings       `embed:"" prefix:"sts-"`
 	StepFunctions                 sfnbackend.Settings       `embed:"" prefix:"stepfunctions-"`
+	AzureBlob                     azureblobbackend.Settings `embed:"" prefix:"azure-blob-"`
 	PortRangeStart                int                       `                                  name:"port-range-start"        env:"PORT_RANGE_START"        default:"10000"         help:"Start of the port range for resource endpoints."`                                                                                                                                              //nolint:lll // config struct tags are intentionally verbose
 	PortRangeEnd                  int                       `                                  name:"port-range-end"          env:"PORT_RANGE_END"          default:"10100"         help:"End (exclusive) of the port range for resource endpoints."`                                                                                                                                    //nolint:lll // config struct tags are intentionally verbose
 	EC2DockerSSHPortMin           int                       `                                  name:"ec2-docker-ssh-port-min" env:"EC2_DOCKER_SSH_PORT_MIN" default:"0"             help:"Lower bound of the host TCP port range used to map EC2-docker SSH (0 = let Docker pick)."`                                                                                                     //nolint:lll // config struct tags are intentionally verbose
@@ -521,6 +523,11 @@ func (c *CLI) GetS3Settings() s3backend.Settings {
 	return c.S3
 }
 
+// GetAzureBlobSettings returns Azure Blob settings (azureblob.ConfigProvider).
+func (c *CLI) GetAzureBlobSettings() azureblobbackend.Settings {
+	return c.AzureBlob
+}
+
 // GetS3Endpoint returns the configured S3 endpoint (s3.ConfigProvider).
 func (c *CLI) GetS3Endpoint() string {
 	s3Port := strings.TrimPrefix(c.Port, ":")
@@ -1845,6 +1852,46 @@ func setupPortAllocator(
 	return alloc
 }
 
+// reserveFixedServicePorts marks ports bound directly by services outside
+// the shared PortAlloc pool as unavailable within that pool, so Acquire
+// never hands the same port number to a different caller.
+//
+// AzureBlob's dedicated listener (services/azureblob) binds a fixed,
+// protocol-conventional default port (10000, matching Azurite's own Blob
+// service port) via a raw net.Listen call, not through PortAlloc -- and that
+// default sits squarely inside PortRangeStart/PortRangeEnd's own default
+// range (10000-10100). Without this reservation, PortAlloc has no way to
+// know AzureBlob already holds 10000 and could hand it to an unrelated
+// caller (e.g. an ElastiCache instance), which would only surface later as
+// a confusing address-in-use failure when that caller tries to actually
+// bind it. See AZURE.md section 4 for the full rationale.
+//
+// A failed reservation is logged, not fatal: AzureBlob's own StartWorker
+// bind is still synchronous and fails fast on a genuine conflict (see
+// handler.go), so the worst outcome here is losing this early-warning
+// cross-service protection, not an unrecoverable startup failure.
+func reserveFixedServicePorts(ctx context.Context, log *slog.Logger, alloc *portalloc.Allocator, cli CLI) {
+	if alloc == nil {
+		return
+	}
+
+	if err := alloc.Reserve(cli.AzureBlob.Port, "azureblob"); err != nil {
+		log.WarnContext(ctx, "failed to reserve AzureBlob's fixed port in the shared pool",
+			"port", cli.AzureBlob.Port, "error", err)
+	}
+}
+
+// setupPortAllocatorWithReservations builds the shared port allocator and
+// reserves any fixed ports services bind directly (see
+// reserveFixedServicePorts) before anything else can Acquire from it.
+// Extracted from run() to keep both steps as a single statement there.
+func setupPortAllocatorWithReservations(ctx context.Context, log *slog.Logger, cli CLI) *portalloc.Allocator {
+	alloc := setupPortAllocator(ctx, log, cli.PortRangeStart, cli.PortRangeEnd)
+	reserveFixedServicePorts(ctx, log, alloc, cli)
+
+	return alloc
+}
+
 // run starts the server with the given CLI configuration.
 // It is separated from Run so it can be exercised in tests without [os.Exit].
 func run(ctx context.Context, cli CLI) error {
@@ -1868,7 +1915,7 @@ func run(ctx context.Context, cli CLI) error {
 	)
 
 	// --- Port allocator ---
-	cli.portAlloc = setupPortAllocator(ctx, log, cli.PortRangeStart, cli.PortRangeEnd)
+	cli.portAlloc = setupPortAllocatorWithReservations(ctx, log, cli)
 
 	// --- Embedded DNS server ---
 	var dnsSrv *gopherDNS.Server
@@ -3565,6 +3612,7 @@ func getNewestServiceProviders() []service.Provider {
 
 func getMostRecentServiceProviders() []service.Provider {
 	return []service.Provider{
+		&azureblobbackend.Provider{},
 		&pinpointbackend.Provider{},
 		&pipesbackend.Provider{},
 		&accessanalyzerbackend.Provider{},

cli_azureblob_port_reservation_test.go

@@ -0,0 +1,69 @@
+package main
+
+import (
+	"log/slog"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/blackbirdworks/gopherstack/pkgs/portalloc"
+	azureblobbackend "github.com/blackbirdworks/gopherstack/services/azureblob"
+)
+
+// TestReserveFixedServicePorts is a regression test: services/azureblob binds
+// its dedicated listener directly via net.Listen, not through PortAlloc, but
+// its default port (10000) sits inside PortRangeStart/PortRangeEnd's own
+// default range (10000-10100). Without reserving it, PortAlloc could still
+// hand that same port number to an unrelated caller (e.g. ElastiCache),
+// which would only surface later as a confusing address-in-use failure. See
+// AZURE.md section 4 and pkgs/portalloc.Allocator.Reserve's doc comment.
+func TestReserveFixedServicePorts(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name                string
+		azurePort           int
+		rangeStart          int
+		rangeEnd            int
+		wantBlockedFromPool bool
+	}{
+		{
+			name:      "default azure port collides with default pool range",
+			azurePort: azureblobbackend.DefaultPort, rangeStart: 10000, rangeEnd: 10100,
+			wantBlockedFromPool: true,
+		},
+		{
+			name:      "custom azure port outside a custom pool range",
+			azurePort: 9999, rangeStart: 10000, rangeEnd: 10100,
+			wantBlockedFromPool: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			alloc, err := portalloc.New(tt.rangeStart, tt.rangeEnd)
+			require.NoError(t, err)
+
+			cli := CLI{AzureBlob: azureblobbackend.Settings{Port: tt.azurePort}}
+			reserveFixedServicePorts(t.Context(), slog.Default(), alloc, cli)
+
+			assert.Equal(t, tt.wantBlockedFromPool, alloc.IsAllocated(tt.azurePort), tt.name)
+		})
+	}
+}
+
+// TestReserveFixedServicePorts_NilAllocatorIsNoop covers the disabled-pool
+// path (setupPortAllocator returns nil for an invalid range): nothing to
+// reserve against, must not panic.
+func TestReserveFixedServicePorts_NilAllocatorIsNoop(t *testing.T) {
+	t.Parallel()
+
+	cli := CLI{AzureBlob: azureblobbackend.Settings{Port: azureblobbackend.DefaultPort}}
+
+	assert.NotPanics(t, func() {
+		reserveFixedServicePorts(t.Context(), slog.Default(), nil, cli)
+	})
+}

cmd/checkpins/main.go

@@ -1,6 +1,7 @@
 // Command checkpins verifies that every services/<svc>/PARITY.md sdk_module
-// front-matter pin (aws-sdk-go-v2/service/<name>@v<version>) matches the
-// version go.mod actually requires for that module. A stale pin silently
+// front-matter pin (aws-sdk-go-v2/service/<name>@v<version>, or
+// azure-sdk-for-go/sdk/<path>@v<version> for Azure-backed services) matches
+// the version go.mod actually requires for that module. A stale pin silently
 // undermines every wire-shape claim in the file, since those claims were
 // checked against the pinned version, not whatever go.mod carries now.
 //
@@ -35,6 +36,7 @@ const (
 	goModPath       = "go.mod"
 
 	sdkServiceModulePrefix = "github.com/aws/aws-sdk-go-v2/service/"
+	sdkAzureModulePrefix   = "github.com/Azure/azure-sdk-for-go/sdk/"
 	sdkModuleFieldPrefix   = "sdk_module:"
 )
 
@@ -43,6 +45,14 @@ const (
 // version including its leading "v".
 var pinRe = regexp.MustCompile(`^aws-sdk-go-v2/service/([A-Za-z0-9_-]+)@(v[0-9][0-9A-Za-z.\-+]*)$`)
 
+// azurePinRe matches an sdk_module value shaped like
+// "azure-sdk-for-go/sdk/storage/azblob@v1.8.0" -- azure-sdk-for-go publishes
+// its service clients as nested submodules (sdk/<area>/<name>) rather than
+// aws-sdk-go-v2's flat sdk/service/<name>, so the captured "module" group
+// can itself contain a "/" and must be matched against the same nested path
+// in go.mod (see loadGoModVersions).
+var azurePinRe = regexp.MustCompile(`^azure-sdk-for-go/sdk/([A-Za-z0-9_/-]+)@(v[0-9][0-9A-Za-z.\-+]*)$`)
+
 func main() {
 	if err := run(); err != nil {
 		fmt.Fprintln(os.Stderr, "checkpins:", err)
@@ -105,9 +115,11 @@ func discoverServiceSlugs(dir string) ([]string, error) {
 }
 
 // loadGoModVersions parses go.mod and returns the pinned version (with its
-// leading "v") of every aws-sdk-go-v2/service/<name> requirement, keyed by
-// <name>. Uses golang.org/x/mod/modfile rather than hand-parsing so both
-// block-style and single-line `require` statements are covered correctly.
+// leading "v") of every aws-sdk-go-v2/service/<name> and
+// azure-sdk-for-go/sdk/<path> requirement, keyed by <name>/<path>
+// respectively. Uses golang.org/x/mod/modfile rather than hand-parsing so
+// both block-style and single-line `require` statements are covered
+// correctly.
 func loadGoModVersions(path string) (map[string]string, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {
@@ -121,11 +133,15 @@ func loadGoModVersions(path string) (map[string]string, error) {
 
 	versions := make(map[string]string, len(f.Require))
 	for _, req := range f.Require {
-		name, ok := strings.CutPrefix(req.Mod.Path, sdkServiceModulePrefix)
-		if !ok {
+		if name, ok := strings.CutPrefix(req.Mod.Path, sdkServiceModulePrefix); ok {
+			versions[name] = req.Mod.Version
+
 			continue
 		}
-		versions[name] = req.Mod.Version
+
+		if name, ok := strings.CutPrefix(req.Mod.Path, sdkAzureModulePrefix); ok {
+			versions[name] = req.Mod.Version
+		}
 	}
 
 	return versions, nil
@@ -248,16 +264,20 @@ func splitValueComment(rest string) (string, string) {
 }
 
 // parsePinValue parses a raw sdk_module value (already stripped of its
-// trailing comment) into a module name and version.
+// trailing comment) into a module name and version. It tries the AWS shape
+// first, then the Azure shape (see pinRe/azurePinRe).
 func parsePinValue(value string) (string, string, bool) {
 	v := strings.Trim(strings.TrimSpace(value), `"'`)
 
-	m := pinRe.FindStringSubmatch(v)
-	if m == nil {
-		return "", "", false
+	if m := pinRe.FindStringSubmatch(v); m != nil {
+		return m[1], m[2], true
+	}
+
+	if m := azurePinRe.FindStringSubmatch(v); m != nil {
+		return m[1], m[2], true
 	}
 
-	return m[1], m[2], true
+	return "", "", false
 }
 
 // isModuleCacheOnly reports whether commentText documents the

cmd/checkpins/main_test.go

@@ -13,8 +13,9 @@ func TestEvaluatePin(t *testing.T) {
 	t.Parallel()
 
 	goModVersions := map[string]string{
-		"dlm":      "v1.39.4",
-		"opsworks": "v1.31.0",
+		"dlm":            "v1.39.4",
+		"opsworks":       "v1.31.0",
+		"storage/azblob": "v1.8.0",
 	}
 
 	tests := []struct {
@@ -37,6 +38,19 @@ func TestEvaluatePin(t *testing.T) {
 			wantKind: resultMismatch,
 			wantMsg:  "dlm: recorded v1.30.0, go.mod v1.39.4",
 		},
+		{
+			name:     "matching azure pin",
+			slug:     "azureblob",
+			content:  "service: azureblob\nsdk_module: azure-sdk-for-go/sdk/storage/azblob@v1.8.0   # audited\n",
+			wantKind: resultOK,
+		},
+		{
+			name:     "mismatched azure pin",
+			slug:     "azureblob",
+			content:  "service: azureblob\nsdk_module: azure-sdk-for-go/sdk/storage/azblob@v1.7.0   # stale\n",
+			wantKind: resultMismatch,
+			wantMsg:  "azureblob: recorded v1.7.0, go.mod v1.8.0",
+		},
 		{
 			name: "module cache only documented",
 			slug: "opsworks",
@@ -108,6 +122,7 @@ go 1.26.5
 
 require (
 	github.com/aws/aws-sdk-go-v2/service/dlm v1.39.4
+	github.com/Azure/azure-sdk-for-go/sdk/storage/azblob v1.8.0
 	github.com/other/pkg v0.1.0
 )
 
@@ -120,5 +135,6 @@ require github.com/aws/aws-sdk-go-v2/service/opsworks v1.31.0
 
 	assert.Equal(t, "v1.39.4", versions["dlm"])
 	assert.Equal(t, "v1.31.0", versions["opsworks"])
+	assert.Equal(t, "v1.8.0", versions["storage/azblob"])
 	assert.NotContains(t, versions, "pkg")
 }