AppSurface Search
Section API Reference
API Reference Language: C# Component: Config Audience: developer

GoogleSecretManager

Type

AppSurfaceGoogleSecretManagerDeclarationValidator

Source

Validates convention mappings against the finalized declaration registry during options startup validation.

Type

AppSurfaceGoogleSecretManagerOptionsValidator

Source

Validates AppSurfaceGoogleSecretManagerOptions before provider lookup.

Method

IsValidDeclarationReference

bool IsValidDeclarationReference(AppSurfaceGoogleSecretManagerOptions options, string key, string? version)
Source

Validates a file declaration locally using the same project/default/latest policy as mappings.

Parameters

  • options
    The provider's isolated options snapshot.
  • key
    A short id or a complete projects/.../secrets/.../versions/... resource.
  • version
    An optional version or alias for short ids only.

Returns

Whether the declaration is structurally valid and satisfies the existing options policy.

Remarks

The historical mapping validator remains permissive about resource syntax for compatibility. File declarations additionally reject malformed segments locally, including disabled references. Numeric versions and Google version aliases are accepted; latest still requires explicit opt-in in every environment. No resource identity or diagnostic text escapes this method, and no client is constructed.

Method

IsProjectSegment

bool IsProjectSegment(string? value)
Source

Rejects path separators, escaping, whitespace and empty project segments without normalizing ids.

Remarks

Project ids/numbers and legacy domain-scoped projects are preserved; project existence is remote.

Method

IsSecretId

bool IsSecretId(string value)
Source

Checks the Secret Manager secret-id character set and 255-character limit.

Method

IsVersionSegment

bool IsVersionSegment(string? value)
Source

Accepts numeric versions or bounded aliases, preserving case and explicit latest policy.

Remarks

Alias syntax follows the Secret resource's versionAliases contract . NEW is reserved. This structural check does not resolve aliases or establish that a numeric version exists.

Type

GoogleSecretManagerConfigResolution<T>

Source

Describes a typed Google Secret Manager configuration resolution.

Type parameters

  • T
    The requested configuration type.
Method

Unclaimed

GoogleSecretManagerConfigResolution<T> Unclaimed()
Source

Creates an unclaimed resolution.

Returns

An unclaimed resolution.

Method

Found

GoogleSecretManagerConfigResolution<T> Found(T? value, string source)
Source

Creates a found resolution.

Parameters

  • value
    The converted value.
  • source
    The source name.

Returns

A found resolution.

Method

Failed

GoogleSecretManagerConfigResolution<T> Failed(GoogleSecretManagerResultStatus status, ConfigProviderTerminalDiagnostic diagnostic, string source)
Source

Creates a failed claimed-key resolution.

Parameters

  • status
    The failed status.
  • diagnostic
    The display-safe diagnostic.
  • source
    The source name.

Returns

A failed resolution.

Property

Status

GoogleSecretManagerResultStatus Status { get; } Source

Gets the resolution status.

Property

Value

T? Value { get; } Source

Gets the converted value when Status is GoogleSecretManagerResultStatus.Found .

Property

Diagnostic

ConfigProviderTerminalDiagnostic? Diagnostic { get; } Source

Gets the display-safe terminal diagnostic when resolution failed for a claimed key.

Property

Source

string? Source { get; } Source

Gets the provider source name.

Type

AppSurfaceGoogleSecretConvention

Source

Describes a scoped convention resolver for Google Secret Manager mappings.

Parameters

  • LogicalKeyPrefix
    The logical-key prefix this convention may claim.
  • SecretIdPrefix
    The optional prefix prepended to normalized secret ids.
  • Version
    The optional version or alias used by this convention.
Type

GoogleSecretManagerConfigProvider

Source

Resolves explicitly claimed AppSurface keys from Google Secret Manager.

Method

Resolve

ConfigProviderValueResult<T> Resolve<T>(ConfigProviderRequest request)
Source

Remarks

Rechecks the resource claim before publishing a value so a collision discovered during a shared fetch or conversion remains terminal for the pending resolution, including cached values.

Method

GetValue

T? GetValue<T>(string environment, string key)
Source

Resolves a strict string key through the compatibility surface.

Parameters

  • environment
    The environment name.
  • key
    The colon-delimited logical key.
Method

ResolveValue

GoogleSecretManagerConfigResolution<T> ResolveValue<T>(string environment, string key)
Source

Resolves a strict string key through the compatibility result surface.

Parameters

  • environment
    The environment name.
  • key
    The colon-delimited logical key.
Method

ResolveForAudit

ConfigProviderAuditResolution ResolveForAudit(ConfigProviderRequest request, Type valueType, ConfigAuditSourceRole role)
Source

Resolves a typed value while returning source provenance for audit.

Parameters

  • request
    The scoped typed request.
  • valueType
    The requested value type.
  • role
    The audit source role.

Remarks

Source provenance identifies the version returned by Google, including when a requested alias resolves to a numeric version or a project ID resolves to a project number. Cached bytes retain that same source name.

Method

GetReportDiagnostics

IReadOnlyList<ConfigAuditDiagnostic> GetReportDiagnostics(string environment)
Source

Gets provider report diagnostics for the supplied environment.

Parameters

  • environment
    The environment being reported.
Property

Priority

int Priority { get; } Source

Gets this provider's precedence.

Property

Name

string Name { get; } Source

Gets this provider's stable name.

Property

PublishedFlightCount

int PublishedFlightCount { get; } Source

Gets the number of published flights for deterministic retirement tests without exposing resource identities.

Type

AppSurfaceGoogleSecretMigrationEntry

Source

Describes one known Google convention identity that needs an explicit migration mapping.

Property

MapSecretSnippet

string MapSecretSnippet { get; } Source

Gets the exact options call that pins the existing legacy secret id.

Type

AppSurfaceGoogleSecretMigrationInventory

Source

Computes Google convention migration mappings without accessing Secret Manager.

Method

Inventory

2 overloads
IReadOnlyList<AppSurfaceGoogleSecretMigrationEntry> Inventory(AppSurfaceGoogleSecretManagerOptions options, IEnumerable<AppSurfaceConfigKey> knownKeys)
Source

Computes mappings for known keys whose old lossy id differs from the new injective id.

IReadOnlyList<AppSurfaceGoogleSecretMigrationEntry> Inventory(AppSurfaceGoogleSecretManagerOptions options, IEnumerable<AppSurfaceConfigKey> knownKeys, string legacyLogicalKeyPrefix, string legacySecretIdPrefix)
Source

Computes migration mappings using caller-supplied raw legacy convention prefixes.

Parameters

  • options
    The current options, which determine new encoded ids and versions.
  • knownKeys
    The logical keys to inspect.
  • legacyLogicalKeyPrefix
    The historical key prefix, checked with ordinal string.StartsWith(string, StringComparison) semantics after keys are scoped to a current convention by segment ancestry.
  • legacySecretIdPrefix
    The historical id prefix; an empty value is supported.

Returns

Mappings for keys whose historical normalized id differs from the current encoded id.

Exceptions

  • ArgumentNullException
    An argument or a key in knownKeys is null.
  • ArgumentException
    The raw legacy key prefix is empty.
Type

AppSurfaceGoogleSecretMapping

Source

Maps one AppSurface logical configuration key to a Google Secret Manager secret.

Parameters

  • LogicalKey
    The logical AppSurface configuration key.
  • SecretIdOrResourceName
    A short secret id or full Secret Manager version resource name.
  • Version
    The optional version or alias for short secret ids.
Type

AppSurfaceGoogleSecretManagerModule

Source

Registers the AppSurface Google Secret Manager configuration provider.

Type

IAppSurfaceGoogleSecretManagerClient

Source

Reads Secret Manager version payloads for the AppSurface Google Secret Manager provider.

Method

AccessSecretVersion

AppSurfaceGoogleSecretPayload AccessSecretVersion(string resourceName, TimeSpan timeout)
Source

Accesses one Secret Manager version.

Parameters

  • resourceName
    The full Secret Manager version resource name.
  • timeout
    The bounded lookup timeout.

Returns

The secret version payload.

Type

AppSurfaceGoogleSecretTransferDiagnostic

Source

Describes a value-safe Google Secret Manager transfer diagnostic.

Method

ToDisplayString

string ToDisplayString()
Source

Renders the diagnostic for terminal output without secret payloads.

Returns

A display-safe diagnostic string.

Type

AppSurfaceGoogleSecretProbeResult

Source

Describes a value-safe Google Secret Manager probe result.

Parameters

  • Status
    The probe status.
  • ResourceName
    The requested resource name.
  • HasEnabledVersions
    Whether an existing secret has at least one enabled version.
  • Diagnostic
    A display-safe diagnostic for failed probes.
Method

Ready

AppSurfaceGoogleSecretProbeResult Ready(string resourceName, bool hasEnabledVersions = false)
Source

Creates a successful probe result.

Parameters

  • resourceName
    The requested resource name.
  • hasEnabledVersions
    Whether an existing secret has enabled versions.

Returns

The successful probe result.

Method

Failed

AppSurfaceGoogleSecretProbeResult Failed(GoogleSecretManagerTransferStatus status, string resourceName, AppSurfaceGoogleSecretTransferDiagnostic diagnostic)
Source

Creates a failed probe result.

Parameters

  • status
    The failure status.
  • resourceName
    The requested resource name.
  • diagnostic
    The display-safe diagnostic.

Returns

The failed probe result.

Type

AppSurfaceGoogleSecretWriteResult

Source

Describes a value-safe Google Secret Manager write result.

Parameters

  • Status
    The write status.
  • ResourceName
    The requested secret parent resource name.
  • WrittenVersionResourceName
    The written version resource name, when Google returned one.
  • Diagnostic
    A display-safe diagnostic for failed writes.
Method

Written

AppSurfaceGoogleSecretWriteResult Written(string resourceName, string? writtenVersionResourceName)
Source

Creates a successful write result.

Parameters

  • resourceName
    The secret parent resource name.
  • writtenVersionResourceName
    The written version resource name.

Returns

The successful write result.

Method

Failed

AppSurfaceGoogleSecretWriteResult Failed(GoogleSecretManagerTransferStatus status, string resourceName, AppSurfaceGoogleSecretTransferDiagnostic diagnostic)
Source

Creates a failed write result.

Parameters

  • status
    The failure status.
  • resourceName
    The requested secret parent resource name.
  • diagnostic
    The display-safe diagnostic.

Returns

The failed write result.

Type

AppSurfaceGoogleSecretAccessResult

Source

Describes a value-safe Google Secret Manager payload access result.

Parameters

  • Status
    The access status.
  • ResourceName
    The requested version resource name.
  • Payload
    The payload when access succeeded.
  • Diagnostic
    A display-safe diagnostic for failed access.
Method

Accessed

AppSurfaceGoogleSecretAccessResult Accessed(string resourceName, AppSurfaceGoogleSecretPayload payload)
Source

Creates a successful access result.

Parameters

  • resourceName
    The requested version resource name.
  • payload
    The accessed payload.

Returns

The successful access result.

Method

Failed

AppSurfaceGoogleSecretAccessResult Failed(GoogleSecretManagerTransferStatus status, string resourceName, AppSurfaceGoogleSecretTransferDiagnostic diagnostic)
Source

Creates a failed access result.

Parameters

  • status
    The failure status.
  • resourceName
    The requested version resource name.
  • diagnostic
    The display-safe diagnostic.

Returns

The failed access result.

Type

IAppSurfaceGoogleSecretTransferClient

Source

Probes and writes Google Secret Manager resources for explicit AppSurface secret transfer workflows.

Remarks

This seam is intentionally separate from IAppSurfaceGoogleSecretManagerClient , which remains the read-only runtime configuration provider client. Implementations must keep diagnostics value-safe and must not create, disable, destroy, rotate, or provision secrets. Version 1 transfer workflows can write an existing Google secret; version 2 workflows use this client only to probe and read a pinned Google version before guarded local materialization.

Method

ProbeSecret

AppSurfaceGoogleSecretProbeResult ProbeSecret(string secretResourceName, TimeSpan timeout)
Source

Probes one existing Google Secret Manager secret parent.

Parameters

  • secretResourceName
    The full projects/.../secrets/... resource name.
  • timeout
    The bounded probe timeout.

Returns

The probe result.

Method

ProbeSecretVersion

AppSurfaceGoogleSecretProbeResult ProbeSecretVersion(string versionResourceName, TimeSpan timeout)
Source

Probes one existing Google Secret Manager secret version.

Parameters

  • versionResourceName
    The full projects/.../secrets/.../versions/... resource name.
  • timeout
    The bounded probe timeout.

Returns

The probe result, whose resource name is the canonical provider response identity.

Method

AccessSecretVersion

AppSurfaceGoogleSecretAccessResult AccessSecretVersion(string versionResourceName, TimeSpan timeout)
Source

Accesses one Google Secret Manager version payload for an apply operation.

Parameters

  • versionResourceName
    The full version resource name.
  • timeout
    The bounded access timeout.

Returns

The version payload.

Method

AddSecretVersion

AppSurfaceGoogleSecretWriteResult AddSecretVersion(string secretResourceName, string value, TimeSpan timeout)
Source

Adds a new enabled version to an existing Google Secret Manager secret.

Parameters

  • secretResourceName
    The full secret parent resource name.
  • value
    The UTF-8 text secret value.
  • timeout
    The bounded write timeout.

Returns

The write result.

Type

GoogleSecretManagerTransferClientAdapter

Source

Default transfer client backed by Google Cloud Secret Manager.

Method

FromCredentialFile

GoogleSecretManagerTransferClientAdapter FromCredentialFile(string credentialFilePath)
Source

Creates a transfer client that uses one explicit service-account credential file.

Parameters

  • credentialFilePath
    Absolute path to the Google credential file.

Returns

A client isolated from ambient Application Default Credentials.

Remarks

Use this factory for operator-owned transfer profiles only. The caller owns file validation and must never include the path or file contents in diagnostics. Runtime configuration continues to use its existing credential flow.

Type

AppSurfaceGoogleSecretManagerOptions

Source

Configures the AppSurface Google Secret Manager provider.

Remarks

Keys are claimed explicitly by MapSecret(string, string, string?) or by an opt-in convention resolver. Claimed keys fail closed by default when Google Secret Manager cannot safely return the value. Environment variables still remain the top AppSurface emergency override because DefaultConfigManager checks them before normal providers.

Method

AllowLatest

AppSurfaceGoogleSecretManagerOptions AllowLatest()
Source

Allows use of the mutable latest Secret Manager version alias.

Returns

The same options instance.

Method

MapSecret

2 overloads
AppSurfaceGoogleSecretManagerOptions MapSecret(string logicalKey, string secretIdOrResourceName, string? version = null)
Source

Maps an AppSurface logical configuration key to a Google Secret Manager secret id or full version resource name.

Parameters

  • logicalKey
    The logical AppSurface configuration key, for example Stripe:ApiKey .
  • secretIdOrResourceName
    A short secret id or full projects/.../secrets/.../versions/... name.
  • version
    The version or alias for short secret ids. Overrides DefaultVersion .

Returns

The same options instance.

AppSurfaceGoogleSecretManagerOptions MapSecret(AppSurfaceConfigKey logicalKey, string secretIdOrResourceName, string? version = null)
Source

Maps a parsed logical key to a Google Secret Manager resource.

Parameters

  • logicalKey
    The parsed logical AppSurface configuration key; dots remain literal segment content.
  • secretIdOrResourceName
    A short secret id or full projects/.../secrets/.../versions/... name.
  • version
    The version or alias for short secret ids. Overrides DefaultVersion .

Returns

The same options instance.

Exceptions

  • ArgumentNullException
    logicalKey is null .
Method

EnableConventionResolver

2 overloads
AppSurfaceGoogleSecretManagerOptions EnableConventionResolver(string logicalKeyPrefix, string secretIdPrefix, string? version = null)
Source

Enables a scoped convention resolver for logical keys under logicalKeyPrefix .

Parameters

  • logicalKeyPrefix
    The required logical-key prefix that the convention may claim.
  • secretIdPrefix
    The non-empty exact prefix prepended to encoded secret ids.
  • version
    The version or alias used by claimed convention keys.

Returns

The same options instance.

AppSurfaceGoogleSecretManagerOptions EnableConventionResolver(AppSurfaceConfigKey logicalKeyPrefix, string secretIdPrefix, string? version = null)
Source

Enables a convention resolver under a parsed logical-key prefix.

Parameters

  • logicalKeyPrefix
    The required logical-key prefix that the convention may claim.
  • secretIdPrefix
    The required non-empty exact prefix prepended to encoded secret ids.
  • version
    The version or alias used by claimed convention keys.

Returns

The same options instance.

Method

CreateSnapshot

AppSurfaceGoogleSecretManagerOptions CreateSnapshot()
Source

Copies host settings and registration collections for a single provider's lifetime.

Returns

An isolated options instance owned exclusively by the provider.

Remarks

Mappings and conventions contain only immutable strings. Copying their collections prevents later additions or host-option changes from altering validation, access, or cache identity.

Property

ProjectId

string? ProjectId { get; set; } Source

Gets or sets the Google Cloud project id used for short secret ids.

Property

DefaultVersion

string? DefaultVersion { get; set; } Source

Gets or sets the default secret version used by mappings that do not specify one.

Remarks

Keep this unset for production unless every mapping supplies its own version or alias. Set AllowLatestVersion before using latest ; mutable latest is an explicit opt-in, not the silent production default.

Property

AllowLatestVersion

bool AllowLatestVersion { get; set; } Source

Gets or sets a value indicating whether the mutable latest version alias is allowed.

Property

FailClosedOnProviderFailure

bool FailClosedOnProviderFailure { get; set; } Source

Gets or sets a value indicating whether a failed raw whole-root base stops fallback to lower-priority bases.

Remarks

Applies only when this provider supplies a raw whole-root base for a Secret{T} root. File-declared scalar references and the logical-key provider contract always report claimed failures.

Property

LookupTimeout

TimeSpan LookupTimeout { get; set; } Source

Gets or sets the bounded timeout for one Secret Manager lookup.

Property

CacheTtl

TimeSpan? CacheTtl { get; set; } Source

Gets or sets the optional in-memory cache duration for successful secret values.

Remarks

Leave unset for strict read-through behavior. When enabled, rotation is visible after this duration or after the app rebuilds the provider. The provider does not run background refresh.

Property

CacheCapacity

int CacheCapacity { get; set; } Source

Gets or sets the maximum number of successful payloads retained by the bounded cache.

Property

MaxAdHocClaims

int MaxAdHocClaims { get; set; } Source

Gets or sets the maximum number of ad-hoc exact-resource claims retained by this provider.

Property

Mappings

IReadOnlyList<AppSurfaceGoogleSecretMapping> Mappings { get; } Source

Gets explicit logical-key to Secret Manager mappings.

Property

Conventions

IReadOnlyList<AppSurfaceGoogleSecretConvention> Conventions { get; } Source

Gets opt-in convention resolvers.

Type

GoogleSecretManagerClientAdapter

Source

Default IAppSurfaceGoogleSecretManagerClient backed by Google Cloud Secret Manager.

Remarks

The default constructor creates the Google client lazily so applications that register the provider but do not resolve Google-backed keys avoid opening Secret Manager transport during service registration.

Type

AppSurfaceGoogleSecretPayload

Source

Carries one Google Secret Manager version payload.

Remarks

Payload bytes are copied when received and whenever returned, so callers cannot mutate provider-owned data. The resolved name is the service response's exact version name. It may differ from the requested name when Google resolves a version alias or a project ID to its numeric identifier. The provider requires this name for source provenance and validates it before publishing or caching the payload.

Property

Data

byte[] Data { get; } Source

Gets a defensive copy of the raw payload bytes.

Property

ResolvedResourceName

string? ResolvedResourceName { get; } Source

Gets the exact resolved Secret Manager version resource name, if available.

Type

ServiceCollectionGoogleSecretManagerExtensions

Source

Provides service collection helpers for AppSurface Google Secret Manager.

Method

ConfigureAppSurfaceGoogleSecretManager

IServiceCollection ConfigureAppSurfaceGoogleSecretManager(this IServiceCollection services, Action<AppSurfaceGoogleSecretManagerOptions> configure)
Source

Configures Google Secret Manager options.

Parameters

  • services
    The service collection to configure.
  • configure
    The options callback.

Returns

The original service collection.

Method

UseAppSurfaceGoogleSecretManagerClient

2 overloads
IServiceCollection UseAppSurfaceGoogleSecretManagerClient<TClient>(this IServiceCollection services)
Source

Replaces the Google Secret Manager client seam.

Type parameters

  • TClient
    The client implementation type.

Parameters

  • services
    The service collection to configure.

Returns

The original service collection.

IServiceCollection UseAppSurfaceGoogleSecretManagerClient(this IServiceCollection services, IAppSurfaceGoogleSecretManagerClient client)
Source

Replaces the Google Secret Manager client seam with a specific instance.

Parameters

  • services
    The service collection to configure.
  • client
    The client instance.

Returns

The original service collection.

Method

UseAppSurfaceGoogleSecretTransferClient

2 overloads
IServiceCollection UseAppSurfaceGoogleSecretTransferClient<TClient>(this IServiceCollection services)
Source

Replaces the Google Secret Manager transfer client seam.

Type parameters

  • TClient
    The transfer client implementation type.

Parameters

  • services
    The service collection to configure.

Returns

The original service collection.

IServiceCollection UseAppSurfaceGoogleSecretTransferClient(this IServiceCollection services, IAppSurfaceGoogleSecretTransferClient client)
Source

Replaces the Google Secret Manager transfer client seam with a specific instance.

Parameters

  • services
    The service collection to configure.
  • client
    The transfer client instance.

Returns

The original service collection.

Enum

GoogleSecretManagerResultStatus

Source

Classifies Google Secret Manager configuration resolution outcomes.

Enum

GoogleSecretManagerTransferStatus

Source

Classifies Google Secret Manager transfer operations without exposing payload bytes.