# Go

Documentation version: 0.3.1.

> [!NOTE]
> SDKs are read-only. The CLI creates vaults and sets secret values;
> applications do not need a CLI process running alongside them.

## Project setup options

1. **Option 1: Set up with the CLI.** Follow the [CLI installation guide](https://sourceorrery.ai/getting-started/#install),
   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](https://sourceorrery.ai/guides/ai-agents/)
   works with an existing CLI installation.

## Install




Two parts: the Go module, from the module proxy, and the native library it
links, from the release (or [built from source](https://sourceorrery.ai/sdks/go/#building-from-source)).

### The module

```bash
go get github.com/netizine/sourceorrery/bindings/go@v0.3.1
```

[The module on pkg.go.dev](https://pkg.go.dev/github.com/netizine/sourceorrery/bindings/go)
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 native library, from the release

The shared library comes from the `sourceorrery-ffi-0.3.1-<target>`
archive on the
[v0.3.1 release](https://github.com/Netizine/sourceorrery/releases/tag/v0.3.1).
Download the archive for your platform, unpack it, and tell the linker and
the loader where it is:



#### Windows

```powershell
$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.

#### macOS

```bash
release=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1
archive=sourceorrery-ffi-0.3.1-aarch64-apple-darwin        # x86_64-apple-darwin on Intel
curl -LO "$release/$archive.tar.gz"
sudo mkdir -p /opt/sourceorrery && sudo tar xzf "$archive.tar.gz" --no-same-owner -C /opt/sourceorrery --strip-components=1

export CGO_LDFLAGS="-L/opt/sourceorrery"
export DYLD_LIBRARY_PATH=/opt/sourceorrery
go build ./...
```

#### Linux

```bash
release=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1
archive=sourceorrery-ffi-0.3.1-x86_64-unknown-linux-gnu    # aarch64-unknown-linux-gnu on arm64
curl -LO "$release/$archive.tar.gz"
sudo mkdir -p /opt/sourceorrery && sudo tar xzf "$archive.tar.gz" --no-same-owner -C /opt/sourceorrery --strip-components=1

export CGO_LDFLAGS="-L/opt/sourceorrery"
export LD_LIBRARY_PATH=/opt/sourceorrery
go build ./...
```



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.

## Get a secret

```go
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](https://sourceorrery.ai/providers/hashicorp-vault/),
[AWS Secrets Manager](https://sourceorrery.ai/providers/aws-secrets-manager/),
[Azure Key Vault](https://sourceorrery.ai/providers/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`:

```go
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
```

## Errors

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:

```go
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](https://sourceorrery.ai/sdks/#errors).

## Load a project

```go
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.

## Goroutines

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.

## Building from source

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](https://sourceorrery.ai/guides/building-from-source/#what-you-need) 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:

```bash
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:

```bash
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:

```bash
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](https://sourceorrery.ai/guides/building-from-source/#the-sdk-test-vault).
Source: [`bindings/go`](https://github.com/Netizine/sourceorrery/blob/main/bindings/go/README.md).
