Documentation
¶
Overview ¶
Package env provides service identity values derived from environment variables and defaults.
This package defines small types and constructors for common identity fields that are used across go-service for consistent naming/versioning and outbound metadata, such as:
- service name (Name)
- service version (Version)
- service instance id (ID)
- service user id (UserID)
- HTTP User-Agent value (UserAgent)
Environment variable overrides ¶
Constructors in this package typically prefer a non-empty environment variable override and otherwise fall back to a derived default:
- SERVICE_NAME: overrides the service name when non-empty (otherwise executable name)
- SERVICE_VERSION: overrides the service version when non-empty (otherwise build/runtime version)
- SERVICE_ID: overrides the service instance id when non-empty (otherwise generated)
- SERVICE_USER_ID: overrides the service user id when non-empty (otherwise service name)
Conventions ¶
Identity values are represented as small string wrapper types with String methods. These wrappers preserve the underlying semantics while keeping imports consistent across go-service.
Start with NewName, NewVersion, NewID, NewUserID, and NewUserAgent.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( di.Constructor(NewID), di.Constructor(NewUserAgent), di.Constructor(NewUserID), )
Module wires env-based service identity values into go.uber.org/fx/go.uber.org/dig.
It provides constructors for commonly used identity primitives derived from environment variables with sensible fallbacks:
- ID via NewID (SERVICE_ID or generated id)
- UserAgent via NewUserAgent ("<name>/<version>")
- UserID via NewUserID (SERVICE_USER_ID or service name)
Note: this module does not provide Name or Version directly; those are commonly constructed by callers using NewName (requires *os.FS) and NewVersion (uses runtime metadata). Consumers that depend on UserAgent typically wire Name and Version elsewhere in their module graph.
Functions ¶
This section is empty.
Types ¶
type Environment ¶
type Environment string
Environment represents the runtime environment a service is running in.
This is typically used to drive environment-specific behavior (for example local/dev/stage/prod), and is commonly carried in configuration as a simple string value.
func (Environment) String ¶
func (e Environment) String() string
String returns the environment value as a string.
This is a convenience method that preserves the underlying string value without normalization.
type ID ¶
type ID string
ID is the service instance identifier.
func NewID ¶
NewID returns a service instance identifier.
It prefers the SERVICE_ID environment variable when set (non-empty); otherwise it falls back to a newly generated id produced by generator.Generate().
Direct callers must pass a non-nil generator when SERVICE_ID is unset or empty. The standard module wiring supplies this generator through the id module.
This is commonly used to distinguish service instances in logs/metrics/traces when multiple replicas are running.
type Name ¶
type Name string
Name is the service name.
func NewName ¶
NewName returns the service name.
It prefers the SERVICE_NAME environment variable when non-empty; otherwise it falls back to the executable name as determined by [fs.ExecutableName].
The filesystem dependency exists to support consistent name derivation across environments and to enable tests to control the executable name behavior. Direct callers must pass a non-nil filesystem when SERVICE_NAME is unset or empty.
type UserAgent ¶
type UserAgent string
UserAgent is the HTTP User-Agent value for this service.
func NewUserAgent ¶
NewUserAgent returns the service User-Agent value.
The returned value is formatted as:
"<name>/<version>"
Name and version come from the provided Name and Version values, including any normalization performed by Version.String.
This value is commonly used for outbound HTTP clients so requests can be attributed to a specific service and version by upstreams.
type UserID ¶ added in v2.28.0
type UserID string
UserID is the service user identifier.
func NewUserID ¶ added in v2.28.0
NewUserID returns a service user identifier.
It prefers the SERVICE_USER_ID environment variable when set (non-empty); otherwise it falls back to the service name.
This value is commonly used when a stable "user" identity is required for integrations that need a username/user-id concept, but where the service itself is the actor.
type Version ¶
type Version string
Version is the service version.
It is typically derived from SERVICE_VERSION (if set) or from runtime/build metadata.
func NewVersion ¶
func NewVersion() Version
NewVersion returns the service version.
It prefers the SERVICE_VERSION environment variable when non-empty; otherwise it falls back to runtime.Version().
The returned Version is not normalized at construction time; normalization is applied when calling Version.String.
Source Files