Skip to main content

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

MethodReturnsDescription
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)boolFlag 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()errorStops 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:
  1. Kubernetes - /var/run/secrets/kubernetes.io/serviceaccount/token exists
  2. AWS - AWS_ROLE_ARN env set or IMDS reachable
  3. GCP - GOOGLE_APPLICATION_CREDENTIALS set or metadata server reachable
  4. 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

ErrorCause
nexus.ErrPublicKeyRestrictedGetSecret called with pk_live_ key
nexus.ErrServiceKindMismatchGetSecret called on kind=frontend service
nexus.ErrBilling402 - billing blocked
nexus.WIFNotConfiguredWIF enabled but provider not detected
nexus.WIFTokenExchangeFailedServer rejected the OIDC token
nexus.SessionExpiredWIF session expired and refresh failed