Documentation Index
Fetch the complete documentation index at: https://docs.nexus.westyx.cloud/llms.txt
Use this file to discover all available pages before exploring further.
Installation
go get gitlab.com/westyx/nexus/sdk/go
Requires Go 1.26+. The module is public - no GitLab credentials needed.
Quick start
package main
import (
"context"
"log"
nexus "gitlab.com/westyx/nexus/sdk/go"
)
func main() {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
client, err := nexus.NewClient(ctx, nexus.Config{
BaseURL: "https://your-service.nexus.westyx.dev",
APIKey: "sk_live_...",
})
if err != nil {
log.Fatal(err) // initial sync failed - do not ignore
}
go client.RunStream(ctx) // SSE live updates
dbURL, _ := client.GetConfig("database.url")
stripe, _ := client.GetSecret("stripe.key")
newUI := client.GetFlag("new.ui", false)
log.Printf("db=%s stripe=%d-bytes newUI=%v", dbURL, len(stripe), newUI)
}
Configuration reference
nexus.Config{
BaseURL: "https://your-service.nexus.westyx.dev", // required
APIKey: "sk_live_...", // required unless WIF
TTL: 5 * time.Minute, // default: 5m
HTTPClient: &http.Client{Timeout: 10 * time.Second},
WIF: &nexus.WIFConfig{...}, // see WIF section
Observer: &nexus.StreamObserver{...}, // optional hooks
}
API
| Method | Returns | Description |
|---|
GetConfig(key) | (string, bool) | Config value; false if missing |
GetConfigAs[T](key) | (T, bool) | Typed config (int, float64, bool) |
GetConfigJSON(key) | (any, bool) | Parsed JSON config value |
GetSecret(key) | ([]byte, error) | Secret bytes; error on pk_ key or frontend kind |
GetSecretFilePath(key) | (string, error) | Temp file path for file-type secrets |
GetFlag(key, default) | bool | Flag value; default if not found |
EvaluateAB(ctx, keys, userID, attrs) | (map[string]bool, error) | A/B evaluation |
RunStream(ctx) | - | Starts SSE listener; blocks until ctx done |
Kind() | string | "backend" or "frontend" |
Close() | error | Stops background goroutines |
Workload Identity Federation
Eliminate static API keys on Kubernetes, AWS, GCP, or Azure:
client, err := nexus.NewClient(ctx, nexus.Config{
BaseURL: "https://your-service.nexus.westyx.dev",
WIF: &nexus.WIFConfig{
Enabled: true,
Provider: nexus.WIFProviderAuto, // "kubernetes" | "aws" | "gcp" | "azure" | "auto"
},
})
Provider auto-detection order:
- Kubernetes -
/var/run/secrets/kubernetes.io/serviceaccount/token exists
- AWS -
AWS_ROLE_ARN env set or IMDS reachable
- GCP -
GOOGLE_APPLICATION_CREDENTIALS set or metadata server reachable
- Azure - IMDS endpoint check
Provide a custom TokenSource to override auto-detection:
WIF: &nexus.WIFConfig{
Enabled: true,
TokenSource: func(ctx context.Context) (string, error) {
return fetchMyOIDCToken(), nil
},
}
Stream observer hooks
nexus.Config{
Observer: &nexus.StreamObserver{
OnConnected: func() { log.Println("stream connected") },
OnEvent: func(e nexus.StreamEvent) { log.Printf("event: %s", e.Type) },
OnReconnectAttempt: func(n int, err error) { log.Printf("reconnect #%d: %v", n, err) },
OnFallback: func(reason string) { log.Printf("fallback: %s", reason) },
},
}
Error types
| Error | Cause |
|---|
nexus.ErrPublicKeyRestricted | GetSecret called with pk_live_ key |
nexus.ErrServiceKindMismatch | GetSecret called on kind=frontend service |
nexus.ErrBilling | 402 - billing blocked |
nexus.WIFNotConfigured | WIF enabled but provider not detected |
nexus.WIFTokenExchangeFailed | Server rejected the OIDC token |
nexus.SessionExpired | WIF session expired and refresh failed |