Skip to content

Go

The read-only Go SDK (cgo over the C ABI): install the module and the native library, or build from source, open a vault, get a secret, match errors by sentinel, load a project.

6 min read
  1. Option 1: Set up with the CLI. Follow the CLI installation guide, then create the vault and set its secret values in your own terminal.
  2. Option 2: Set up with an AI coding agent. Run sourceorrery init --integration all, then ask your agent to set up SourceOrrery for the project without showing values. You keep vault keys and new values private. The agent setup guide works with an existing CLI installation.

Two parts: the Go module, from the module proxy, and the native library it links, from the release (or built from source).

Terminal window
go get github.com/netizine/sourceorrery/bindings/go@v0.3.1

The module on pkg.go.dev (opens in a new tab) is served by the Go module proxy from the bindings/go/v0.3.1 tag, and go checks it against the Go checksum database. It is a cgo binding over the C ABI with the header vendored in the module, so a C toolchain is required: gcc or clang, or MinGW-w64 gcc on Windows.

The shared library comes from the sourceorrery-ffi-0.3.1-<target> archive on the v0.3.1 release (opens in a new tab). Download the archive for your platform, unpack it, and tell the linker and the loader where it is:

Terminal window
$release = "https://github.com/Netizine/sourceorrery/releases/download/v0.3.1"
$dir = "$env:LOCALAPPDATA\sourceorrery-ffi"
Invoke-WebRequest "$release/sourceorrery-ffi-0.3.1-x86_64-pc-windows-msvc.zip" -OutFile sourceorrery-ffi.zip # aarch64-pc-windows-msvc on Arm
Expand-Archive sourceorrery-ffi.zip -DestinationPath $dir -Force
$env:CGO_LDFLAGS = "-L$dir"
$env:Path = "$dir;$env:Path" # sourceorrery_ffi.dll must be on PATH at run time
go build ./...

On Windows the binding links sourceorrery_ffi.dll directly, because the static archive next to it is built by MSVC and MinGW cannot consume it.

Verify a download against the release’s SHA256SUMS before unpacking it. Static linking against libsourceorrery_ffi.a from the same archive works too on Linux and macOS (-lsourceorrery_ffi -lpthread -ldl -lm on Linux), and then nothing has to be on the loader’s path at run time.

import sourceorrery "github.com/netizine/sourceorrery/bindings/go"
reader, err := sourceorrery.Open("development", nil)
if err != nil {
return err
}
defer reader.Close()
secret, err := reader.Get("database-password")
if err != nil {
return err
}
defer secret.Close() // zeroises the value
connect(secret.Value.Text())

With the default options, SOURCEORRERY_HOME locates the vault; this machine’s key in the OS credential store opens it, else the recovery key: an explicit one, SOURCEORRERY_RECOVERY_KEY, then a file or SOURCEORRERY_RECOVERY_KEY_FILE. &sourceorrery.OpenOptions{Home, RecoveryKey, RecoveryKeyFile, IgnoreEnvironment} overrides any of that (wipe RecoveryKey after use). The SDK never prompts and never asks the vault’s view check.

A secret the vault keeps at a provider (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) is read there through the vault’s connection, with the same calls: the connection signs in with the credentials it stores, or with the provider’s own sign-in on the machine. No provider is contacted until a secret it keeps is read.

Call Returns
reader.Get(name) *Secret for the newest accessible version
reader.GetVersion(name, version) *Secret for exactly that version
reader.Properties(name, version) ("" for the newest) SecretProperties (policy not applied)
reader.Resolve("sourceorrery://development/database-password") *Secret
reader.Descriptor() VaultDescriptor (no values)

Secret.Properties (Vault, Name, Version, Enabled, ContentType, Tags, NotBefore, ExpiresOn, CreatedOn, UpdatedOn as time.Time, RecoveryLevel, Reference()) and Secret.Value, a *SecretValue:

value.Bytes() // []byte (a copy)
value.Text() // string
value.Len()
value.Close() // zeroise; Bytes() returns nil afterwards
value.String() // "[REDACTED]"; encoding/json writes "[REDACTED]" too

Every failure is a *sourceorrery.Error with Code, Message and Hint (Error() is the message followed by the hint). errors.Is matches the sentinels by code:

secret, err := reader.Get("database-password")
switch {
case errors.Is(err, sourceorrery.ErrLocked):
var e *sourceorrery.Error
errors.As(err, &e)
log.Println(e.Hint) // which recovery-key sources were tried
case errors.Is(err, sourceorrery.ErrNotFound):
log.Println(err) // "secret ... was not found. Store it with ..."
case errors.Is(err, sourceorrery.ErrPolicy): // disabled, not yet valid or expired
log.Println(err)
case err != nil:
return err
}

Sentinels: ErrNotFound, ErrVersionNotFound, ErrDeleted, ErrDisabled, ErrNotYetValid, ErrExpired, ErrPolicy, ErrInvalidName, ErrInvalidArgument, ErrPermissionDenied, ErrLocked, ErrVaultNotFound, ErrMigrationRequired, ErrVaultMismatch, ErrManifest, ErrCrypto, ErrStorage, ErrUnsupported, ErrUnauthenticated (the provider that stores the secret has no credentials for this process), ErrProviderUnavailable (it could not be reached). (*Error).Transient() is true for not_yet_valid and provider_unavailable. See the SDK overview.

project, err := sourceorrery.LoadProject("sourceorrery.toml", nil) // "" discovers it
if err != nil {
return err
}
defer project.Close()
for _, secret := range project.Secrets {
os.Setenv(secret.Env, secret.Value.Text())
}

LoadProject resolves every [secrets.*] entry the way sourceorrery run does and returns the first required secret’s error if one cannot be read.

A *Reader may be used from several goroutines at once. Each call pins its OS thread while it reads the C ABI’s per-thread error state.

You need Git, Rust 1.91.1 or newer installed with rustup, and a C compiler (on Linux also pkg-config and libdbus-1-dev); Building from source has the commands for each platform. For this SDK, also Go 1.24 or newer, with cgo’s C compiler on PATH (MinGW-w64 gcc on Windows).

The Go code needs no build of its own; what you build is the native library it links:

Terminal window
git clone https://github.com/Netizine/sourceorrery
cd sourceorrery
git checkout v0.3.1 # or stay on main for the newest changes
cargo build --release -p sourceorrery-ffi

The library lands in target/release; use that directory wherever the install steps above use the unpacked archive (CGO_LDFLAGS, and the loader path at run time). To build your module against this checkout’s Go code instead of the published module, point go.mod at it:

Terminal window
go mod edit -replace github.com/netizine/sourceorrery/bindings/go=/path/to/sourceorrery/bindings/go

To run the tests, the example and the conformance harness, build the CLI too, which creates the test vault, and run the rest in Bash (Git Bash on Windows) from the repository root:

Terminal window
cargo build --release -p sourceorrery-cli -p sourceorrery-ffi
eval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault, the variables the tests read, SOURCEORRERY_NATIVE_DIR
cd bindings/go
export CGO_LDFLAGS="-L$SOURCEORRERY_NATIVE_DIR"
export LD_LIBRARY_PATH="$SOURCEORRERY_NATIVE_DIR" DYLD_LIBRARY_PATH="$SOURCEORRERY_NATIVE_DIR"
# Git Bash on Windows: the DLL must be on PATH instead
# export PATH="$(cygpath -u "$SOURCEORRERY_NATIVE_DIR"):$PATH"
go test ./...
go run ./examples/get-secret "$SOURCEORRERY_TEST_VAULT" database-password
go build -o conformance-go ./conformance # conformance-go.exe on Windows
python ../../tests/conformance/sdk/harness.py --runner go

What the fixture script creates: The SDK test vault. Source: bindings/go (opens in a new tab).