azcore

azcore is the foundation module underlying every Azure SDK for Go client library, providing the shared HTTP pipeline, authentication credentials, retry and logging policies, and error types that Azure’s generated and hand-written Go clients build on. Rather than each service client reimplementing request/response handling, azcore centralizes it into a composable Policy pipeline so Storage, Compute, Key Vault, and dozens of other Azure clients all share the same request lifecycle, tracing hooks, and error semantics.

Application developers rarely import azcore directly for its own sake — it typically arrives as a transitive dependency of whichever Azure service SDK they use — but it exposes public building blocks (credentials, custom policies, fakes for testing, and ARM resource-ID helpers) for anyone extending or testing Azure Go clients.

What You Get

• A composable HTTP Policy pipeline (per-call and per-retry policies) shared by all Azure Go SDK clients
• Credential types (TokenCredential, KeyCredential, SASCredential) for authenticating to Azure services
• A typed ResponseError for non-success HTTP responses that works cleanly with errors.As
• Built-in tracing hooks (tracing package) and structured logging (log package) wired into every request
• A fake package for building test doubles of Azure clients without hitting live services
• ARM-specific helpers (arm package) for parsing Azure resource IDs and resource types

Common Use Cases

• Building a custom Azure SDK client or extending generated ones
• Writing unit tests for code that consumes Azure SDKs via the fake package
• Injecting custom policies (e.g. logging, header injection) into Azure client requests
• Parsing and validating ARM resource IDs in infrastructure automation tooling

Under The Hood

Architecture

azcore implements a middleware pipeline pattern (Policy -> Transporter -> Pipeline) for HTTP requests to Azure services. The package is split into focused subpackages — policy, runtime, log, tracing, streaming, arm, cloud, messaging, and fake — each with a narrow responsibility, and internal implementation details live under internal/exported and internal/shared, re-exported at the package root as type aliases to keep the public surface small and stable. Policies chain via a Do(req) method calling req.Next(), the same onion-style middleware pattern used in many Go HTTP servers but applied to outbound client requests. The arm subpackage layers ARM-specific concerns (resource identifiers, resource types, ARM-flavored policies) on top of the generic azcore primitives rather than duplicating them, and fake provides an in-process fake server implementation so consuming code can be tested without azcore’s HTTP layer at all.

Tech Stack

Written in Go 1.25 with almost no external dependencies: golang.org/x/net and golang.org/x/text for network and text handling, go.yaml.in/yaml for YAML support used internally, and stretchr/testify for tests only. It has no web framework or database dependency — it is a client-side library, not a server. Builds with the standard Go toolchain; CI runs through Azure DevOps Pipelines (ci.yml) scoped to the sdk/azcore path within the azure-sdk-for-go monorepo. Distributed tracing integrates through the tracing package’s span-creation hooks rather than a hard dependency on a specific tracing backend.

Code Quality

Test coverage is extensive: roughly 40% of the module’s Go files are _test.go files, using table-driven tests in idiomatic Go style plus testify for assertions. Error handling is explicit and typed — ResponseError wraps non-success HTTP responses and is designed to be unwrapped with errors.As rather than string-matched. Every exported symbol carries a doc comment, which is unusually rigorous even by Go stdlib standards, and the module leans on generics (e.g. NullValue[T]) for type-safe ergonomics. CI enforcement is scoped per-subpackage via path-filtered Azure Pipelines triggers.

What Makes It Unique

azcore’s distinguishing value isn’t a single novel technique — middleware pipelines are a well-known pattern — but the consistency it enforces across the entire Azure SDK for Go surface: every generated and hand-written Azure client shares the same retry, auth, logging, and tracing behavior because they all sit on this one pipeline. The bundled fake package for building test doubles, and the ARM resource-ID parsing built as a thin specialization layer rather than a separate implementation, are the kind of practical conveniences that come from being the shared foundation for dozens of production SDKs rather than a standalone library.