Proveïdor de secrets propi
Com pots fer servir Envilder amb un magatzem de secrets que no suporta, o provar el codi d'arrencada sense compte al núvol? Als SDKs, passa el teu propi proveïdor al builder. El fitxer de mapatge, la validació del contracte i la injecció funcionen igual que amb AWS SSM o Azure Key Vault.
Quan fer-lo servir
Un proveïdor propi substitueix el client d'AWS o Azure que l'SDK construiria a partir de $config. Dos motius habituals:
- Els teus secrets són en un magatzem que Envilder encara no suporta (HashiCorp Vault, 1Password, una base de dades, una API interna).
- Vols provar el codi d'arrencada amb un fake en memòria: sense compte al núvol, sense emulador i sense variables d'entorn.
Només els SDKs (1.2+) accepten un proveïdor propi. El CLI i la GitHub Action suporten AWS SSM i Azure Key Vault.
Com funciona
Un proveïdor implementa una interfície i, opcionalment, una segona per a la validació del contracte:
| Interfície | Mètode (Node.js · Python · .NET) | Per a què serveix |
|---|---|---|
ISecretProvider | getSecrets · get_secret · GetSecret | Resoldre els valors que s'injecten. Els secrets que falten s'ometen, no llancen cap error. |
ISecretExistenceChecker | checkSecretsExist · check_secrets_exist · CheckSecretsExistAsync | Opcional. Validació del contracte: respondre exists o missing per a cada clau sense llegir cap valor. |
Passa la instància amb withSecretProvider() (with_secret_provider() a Python, WithSecretProvider() a .NET). L'SDK ja no construeix cap proveïdor a partir de $config, però continua validant el fitxer de mapatge, així que un error al fitxer que l'app fa servir a producció també falla als tests que fan servir un fake.
Exemple
Un proveïdor en memòria que implementa les dues interfícies, connectat a una càrrega amb validació del contracte:
import {
Envilder,
type ISecretExistenceChecker,
type ISecretProvider,
} from '@envilder/sdk';
const fakeSecrets = new Map([['/app/db-url', 'postgres://localhost/test']]);
class InMemoryProvider implements ISecretProvider, ISecretExistenceChecker {
async getSecrets(names: string[]) {
return new Map(
names.flatMap((name) => {
const value = fakeSecrets.get(name);
return value === undefined ? [] : [[name, value] as const];
}),
);
}
async checkSecretsExist(names: readonly string[]) {
return new Map(
names.map((name) => [
name,
{ status: fakeSecrets.has(name) ? 'exists' : 'missing' } as const,
]),
);
}
}
await Envilder.fromMapFile('envilder.json')
.withSecretProvider(new InMemoryProvider())
.withContractValidation()
.inject();from envilder import (
Envilder,
ISecretExistenceChecker,
ISecretProvider,
SecretExistence,
SecretExistenceStatus,
)
FAKE_SECRETS = {'/app/db-url': 'postgres://localhost/test'}
class InMemoryProvider(ISecretProvider, ISecretExistenceChecker):
def get_secret(self, name):
return FAKE_SECRETS.get(name)
def check_secrets_exist(self, names):
return {
name: SecretExistence(
SecretExistenceStatus.EXISTS
if name in FAKE_SECRETS
else SecretExistenceStatus.MISSING
)
for name in names
}
(
Envilder.from_map_file('envilder.json')
.with_secret_provider(InMemoryProvider())
.with_contract_validation()
.inject()
)using Envilder;
using Envilder.Domain.Ports;
await Env.FromMapFile("envilder.json")
.WithSecretProvider(new InMemoryProvider())
.WithContractValidation()
.InjectAsync();
public sealed class InMemoryProvider : ISecretProvider, ISecretExistenceChecker
{
private readonly Dictionary<string, string> _secrets = new()
{
["/app/db-url"] = "Server=localhost;Database=test",
};
public string? GetSecret(string name) => _secrets.GetValueOrDefault(name);
public Task<string?> GetSecretAsync(string name, CancellationToken ct = default)
=> Task.FromResult(GetSecret(name));
public Task<IReadOnlyDictionary<string, SecretExistence>> CheckSecretsExistAsync(
IReadOnlyCollection<string> names, CancellationToken ct)
=> Task.FromResult<IReadOnlyDictionary<string, SecretExistence>>(names.ToDictionary(
name => name,
name => new SecretExistence(_secrets.ContainsKey(name)
? SecretExistenceStatus.Exists
: SecretExistenceStatus.Missing)));
}Validació del contracte amb un proveïdor propi
- Si el proveïdor implementa ISecretExistenceChecker, validateContract() i withContractValidation() hi comproven cada clau, com amb els proveïdors inclosos.
- Si no, totes les claus surten com a provider_error ("The provider cannot check whether a secret exists."), i una càrrega amb validació del contracte falla en lloc de passar en silenci.
- El camp provider de cada clau manté el tipus configurat: l'override de withProvider(), després $config.provider i, si no, aws.
Consulta la referència d'envilder validate per a tots els estats →
Exemples executables
envilder-examples té un exemple per SDK: un proveïdor sobre un fitxer local xifrat amb AES-256-GCM, amb tests de càrrega, de fallada a l'arrencada quan falta un secret i de validació del contracte sense desxifrar res.