BarelyACompany.Locko 1.1.0

locko-dotnet-sdk

Official .NET SDK for Locko — a secrets and config management tool.

Fetch your runtime configuration and secrets with a single method call, using nothing but the .NET 9 BCL (System.Net.Http, System.Text.Json).

Requirements

• .NET 9.0+

Installation

dotnet add package BarelyACompany.Locko

Quick Start

You need an API key to fetch config. The API key is the one credential you must supply yourself — as a real environment variable, a CI secret, or a vault entry. It authenticates the request to Locko; it cannot come from Locko itself.

using Locko;

// LOCKO_API_KEY must already be set before this runs.
var client = LockoClient.Create(Environment.GetEnvironmentVariable("LOCKO_API_KEY")!);

IReadOnlyDictionary<string, string> config = await client.GetConfigAsync();

var connectionString = config["DATABASE_URL"];

Fetching specific subsets

IReadOnlyDictionary<string, string> secrets   = await client.GetSecretsAsync();   // secret = true
IReadOnlyDictionary<string, string> variables = await client.GetVariablesAsync(); // secret = false

Injecting into environment variables (optional)

If your application framework resolves configuration from environment variables and you want Locko values picked up automatically, inject them before the framework starts:

// false = won't overwrite variables already set in the process
await client.InjectIntoEnvironmentAsync(false);

// true = force-overwrite everything
await client.InjectIntoEnvironmentAsync(true);

// then start your host...
var builder = WebApplication.CreateBuilder(args);

Custom HttpClient

var options = new LockoClientOptions
{
    Timeout = TimeSpan.FromSeconds(15),
};

var client = LockoClient.Create(apiKey, options);

Or inject an entirely custom HttpClient (e.g. with a proxy or for testing):

var options = new LockoClientOptions
{
    HttpClientFactory = () => new HttpClient(myCustomHandler),
};

var client = LockoClient.Create(apiKey, options);

Method Reference

LockoClient.Create(string apiKey)

Creates a new client with default options. apiKey is required and must not be null or whitespace.

LockoClient.Create(string apiKey, LockoClientOptions options)

Creates a new client with custom options.

LockoClient implements IDisposable. Dispose the instance when it is no longer needed to release the underlying socket. In long-lived applications you typically keep a single instance for the lifetime of the process.

using var client = LockoClient.Create(apiKey);
var config = await client.GetConfigAsync();

Client methods (all async)

ConfigEntry properties

LockoClientOptions properties

Error Handling

All errors surface as LockoException:

try
{
    var config = await client.GetConfigAsync();
}
catch (LockoException ex)
{
    Console.Error.WriteLine($"Status: {ex.StatusCode}"); // 0 if no HTTP response
    Console.Error.WriteLine($"Message: {ex.Message}");
}

API

The SDK calls:

GET https://api-locko.barelyacompany.com/api/api-keys/config
X-API-Key: <apiKey>

Response format:

[
  { "key": "DATABASE_URL", "value": "postgres://...", "secret": false },
  { "key": "JWT_SECRET",   "value": "...",            "secret": true  }
]

License

MIT — see LICENSE.