Documentation
¶
Index ¶
- Constants
- func ParseNeonEndpointID(host string) (string, error)
- type CredentialSource
- type GCPSecretManagerClient
- type GCPServiceAccountSource
- type GitHubAppSource
- type NeonResolver
- type RefreshingSource
- type SecretsManagerClient
- type TokenExchangeConfig
- type TokenExchangeResponse
- type TokenExchangeSource
Constants ¶
const DefaultNeonBaseURL = "https://console.neon.tech"
DefaultNeonBaseURL is the production Neon API base URL.
Variables ¶
This section is empty.
Functions ¶
func ParseNeonEndpointID ¶ added in v0.12.0
ParseNeonEndpointID extracts the Neon endpoint ID from a hostname like "ep-cool-darkness-123456.us-east-2.aws.neon.tech". The "-pooler" suffix (connection pooler endpoints) is stripped.
Types ¶
type CredentialSource ¶
CredentialSource fetches a credential value from an external system.
func NewAWSSecretsManagerSource ¶
func NewAWSSecretsManagerSource(secretID, region string) (CredentialSource, error)
NewAWSSecretsManagerSource creates a CredentialSource backed by AWS Secrets Manager.
func NewEnvSource ¶
func NewEnvSource(varName string) CredentialSource
NewEnvSource creates a CredentialSource that reads from an environment variable.
func NewGCPSecretManagerSource ¶ added in v0.8.0
func NewGCPSecretManagerSource(project, secret, version string) (CredentialSource, error)
NewGCPSecretManagerSource creates a CredentialSource backed by GCP Secret Manager. The returned source implements io.Closer to release the underlying gRPC connection.
func NewStaticSource ¶
func NewStaticSource(value string) CredentialSource
NewStaticSource creates a CredentialSource that returns a fixed value.
type GCPSecretManagerClient ¶ added in v0.8.0
type GCPSecretManagerClient interface {
AccessSecretVersion(ctx context.Context, resourceName string) (string, error)
}
GCPSecretManagerClient abstracts the GCP Secret Manager API for testing.
type GCPServiceAccountSource ¶ added in v0.11.0
type GCPServiceAccountSource struct {
// contains filtered or unexported fields
}
GCPServiceAccountSource mints OAuth2 access tokens from a GCP service account key (the JSON file format produced by `gcloud iam service-accounts keys create`). It signs a JWT with the key and exchanges it for an access token at the key's token_uri. It implements both CredentialSource and RefreshingSource.
func NewGCPServiceAccountSource ¶ added in v0.11.0
func NewGCPServiceAccountSource(keyJSON []byte, scopes string) (*GCPServiceAccountSource, error)
NewGCPServiceAccountSource creates a credential source from a service account key JSON. scopes is a space-separated list of OAuth scopes; when empty it defaults to the cloud-platform scope.
func NewGCPServiceAccountSourceFromKeySource ¶ added in v0.11.0
func NewGCPServiceAccountSourceFromKeySource(keySource CredentialSource, scopes string) *GCPServiceAccountSource
NewGCPServiceAccountSourceFromKeySource creates a credential source whose service account key JSON is fetched from another CredentialSource (e.g., GCP Secret Manager) on first use and cached. When the token endpoint rejects an assertion, the cached key is dropped and re-fetched on the next attempt, so key rotation in the backing source is picked up without a restart. Close releases the key source if it implements io.Closer.
func (*GCPServiceAccountSource) Close ¶ added in v0.11.0
func (s *GCPServiceAccountSource) Close() error
Close releases the key source if it implements io.Closer.
func (*GCPServiceAccountSource) Fetch ¶ added in v0.11.0
func (s *GCPServiceAccountSource) Fetch(ctx context.Context) (string, error)
func (*GCPServiceAccountSource) TTL ¶ added in v0.11.0
func (s *GCPServiceAccountSource) TTL() time.Duration
func (*GCPServiceAccountSource) Type ¶ added in v0.11.0
func (s *GCPServiceAccountSource) Type() string
type GitHubAppSource ¶
type GitHubAppSource struct {
// contains filtered or unexported fields
}
GitHubAppSource generates GitHub App installation access tokens. It implements both CredentialSource and RefreshingSource.
func NewGitHubAppSource ¶
func NewGitHubAppSource(appID, installationID string, privateKeyPEM []byte) (*GitHubAppSource, error)
NewGitHubAppSource creates a credential source that generates GitHub App installation tokens. privateKeyPEM must be a PEM-encoded RSA private key.
func (*GitHubAppSource) Fetch ¶
func (s *GitHubAppSource) Fetch(ctx context.Context) (string, error)
func (*GitHubAppSource) TTL ¶
func (s *GitHubAppSource) TTL() time.Duration
func (*GitHubAppSource) Type ¶
func (s *GitHubAppSource) Type() string
type NeonResolver ¶ added in v0.12.0
type NeonResolver struct {
APIKey CredentialSource // source for the Neon API key
// Project is an optional Neon project ID. When set, the resolver queries
// this project directly instead of enumerating all projects — required for
// project-scoped API keys, which cannot list projects.
Project string
BaseURL string // defaults to DefaultNeonBaseURL
TTL time.Duration // password cache TTL; defaults to 5 minutes
HTTPClient *http.Client // defaults to a client with a 15s timeout
// contains filtered or unexported fields
}
NeonResolver resolves Postgres passwords for Neon endpoints via the Neon API. It maps an (endpoint hostname, role, database) tuple to a password by locating the project that owns the endpoint and fetching its connection URI. Resolved passwords are cached for TTL; endpoint-to-project/branch mappings are cached until InvalidatePassword drops them (Neon can reassign an endpoint to a different branch).
The zero value is not usable: APIKey must be set. All other fields are optional. NeonResolver is safe for concurrent use.
func (*NeonResolver) Close ¶ added in v0.12.0
func (r *NeonResolver) Close() error
Close cancels any in-flight Neon API calls so the resolver does not hold up a server shutdown waiting out per-call timeouts. It is safe to call more than once. ResolvePassword calls after Close fail fast with a context error. Close implements io.Closer.
func (*NeonResolver) InvalidatePassword ¶ added in v0.12.0
func (r *NeonResolver) InvalidatePassword(host, user, database string)
InvalidatePassword drops the cached password for the given tuple, along with the endpoint's cached project/branch info (Neon can reassign a compute endpoint to a different branch, e.g. on branch reset). Callers invoke this when authentication fails and then retry once; the retry re-discovers the endpoint and fetches fresh credentials.
func (*NeonResolver) ResolvePassword ¶ added in v0.12.0
func (r *NeonResolver) ResolvePassword(ctx context.Context, host, user, database string) (string, error)
ResolvePassword returns the Postgres password for the given role and database on the Neon endpoint identified by host (e.g. "ep-cool-darkness-123456.us-east-2.aws.neon.tech"). Host comparison is case-insensitive since SNI values are case-insensitive.
func (*NeonResolver) Type ¶ added in v0.12.0
func (r *NeonResolver) Type() string
Type returns the resolver type identifier.
type RefreshingSource ¶
type RefreshingSource interface {
CredentialSource
TTL() time.Duration
}
RefreshingSource is a CredentialSource whose values expire and must be re-fetched periodically. TTL returns the duration until the most recently fetched credential expires. Callers use this to schedule background refresh.
type SecretsManagerClient ¶
type SecretsManagerClient interface {
GetSecretValue(ctx context.Context, secretID string) (string, error)
}
SecretsManagerClient abstracts the AWS Secrets Manager API for testing.
type TokenExchangeConfig ¶ added in v0.5.0
type TokenExchangeConfig struct {
Endpoint string // STS token endpoint URL
ClientID string // OAuth client ID for client credentials auth
ClientSecret string // OAuth client secret
Resource string // Target resource URI (e.g., "https://api.github.com")
SubjectTokenType string // Subject token type URI (defaults to access_token type)
ActorTokenType string // Actor token type URI (defaults to access_token type)
}
TokenExchangeConfig configures an RFC 8693 token exchange source.
type TokenExchangeResponse ¶ added in v0.5.0
type TokenExchangeResponse struct {
AccessToken string `json:"access_token"`
IssuedTokenType string `json:"issued_token_type"`
TokenType string `json:"token_type"`
ExpiresIn int `json:"expires_in"`
}
TokenExchangeResponse is the STS response per RFC 8693 §2.2.1.
type TokenExchangeSource ¶ added in v0.5.0
type TokenExchangeSource struct {
// contains filtered or unexported fields
}
TokenExchangeSource exchanges a subject token for an access token via RFC 8693. It caches tokens per subject with TTL from the STS response.
func NewTokenExchangeSource ¶ added in v0.5.0
func NewTokenExchangeSource(cfg TokenExchangeConfig) *TokenExchangeSource
NewTokenExchangeSource creates a new RFC 8693 token exchange source.
func (*TokenExchangeSource) Exchange ¶ added in v0.5.0
func (s *TokenExchangeSource) Exchange(ctx context.Context, subjectToken, actorToken, requestID string) (*TokenExchangeResponse, error)
Exchange performs an RFC 8693 token exchange for the given subject token. When actorToken is non-empty, it is included as the actor_token parameter. When requestID is non-empty, it is forwarded as X-Request-Id to the STS.
func (*TokenExchangeSource) Resolve ¶ added in v0.5.0
func (s *TokenExchangeSource) Resolve(ctx context.Context, subjectToken, actorToken, requestID string) (string, error)
Resolve returns a credential for the given subject, using the cache when possible. Concurrent requests for the same subject are coalesced into a single STS call via singleflight. When actorToken is non-empty, it is forwarded to the STS as the RFC 8693 actor_token parameter and included in the cache key. When requestID is non-empty, it is forwarded as X-Request-Id to the STS for cross-service correlation.
Source Files