StellNula Go SDK

stellnula-go-sdk is the Go client SDK for stellhub/stellnula-service, the Stell configuration center service also known as Nebula.

Positioning

This SDK provides a Go client for application bootstrap, configuration synchronization, local directory snapshots, snapshot access, listener callbacks, and label-aware configuration delivery.

It does not implement a local configuration center. It delegates configuration resolution and governance rules to stellnula-service, then exposes a Go-friendly snapshot API for applications and platform components.

Capabilities

• Bootstrap synchronization through the StellNula client API.
• HTTP full/delta synchronization with a background recovery loop.
• Application, environment, cluster, namespace, and group scoped configuration lookup.
• Label-aware bootstrap requests for gray configuration and contextual delivery.
• Snapshot access through entries, map view, and single-key/config-id lookup.
• Local directory snapshot persistence compatible with stellnula-java-sdk.
• Bearer token authentication through fixed tokens or a custom token provider.
• OpenTelemetry provider injection points for framework-managed observability.

Current Status

Item	Value
Stability	Early development
Language	Go
Target service	stellnula-service
Transport	HTTP data plane, pluggable gRPC watch adapter
Maintainer	StellHub

Installation

go get github.com/stellhub/stellnula-go-sdk

Quick Start

package main

import (
	"context"
	"fmt"
	"log"

	stellnula "github.com/stellhub/stellnula-go-sdk"
)

func main() {
	client, err := stellnula.NewClient(stellnula.Options{
		Endpoint: "http://localhost:8060",
		AppID:    "example-service",
		ClientID: "example-service-local",
		Env:      "dev",
		// Use stellnula.Bool(false) when binding Options directly and
		// you need to override a default-true boolean field.
		WatchEnabled: stellnula.Bool(false),
		Labels: map[string]string{
			"region": "local",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	snapshot, err := client.SyncNow(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	if value, ok := snapshot.GetValue("feature.enabled"); ok {
		fmt.Println(value)
	}
}

API Surface

API	Responsibility
NewClient(options, opts...)	Create a StellNula SDK client
Start(ctx)	Load local snapshot, bootstrap remote config, and start watch/recovery loop
SyncNow(ctx)	Fetch the latest bootstrap snapshot
FetchFull(ctx)	Fetch a full snapshot through the data-plane path
Snapshot()	Return the current in-memory snapshot
AsMap()	Return the latest value by config key
GetValue(key)	Return a single config value by config key or config id
Listen(...)	Receive config change callbacks

WatchEnabled and GRPCPlaintext are pointer booleans so a framework can distinguish an omitted value from an explicit false. Use stellnula.Bool(false) in struct literals, or stellnula.WithWatchEnabled(false) / stellnula.WithGRPCPlaintext(false) when using functional options.

Local Snapshot

The default local snapshot directory follows the Java SDK layout:

${HOME}/.stellnula/${appId}/${env}/${cluster}
├── .stellnula-snapshot.json
└── configs/
    └── <configKey>

The metadata file stores revision, checksum, and entry indexes. Config content is materialized under configs/. Unsafe paths are sanitized or stored under configs/by-id/.

Development

Run verification:

go test ./...

Repository Scope

The SDK core does not depend on Stellar. Framework integration should inject shared HTTP/gRPC resources, token providers, loggers, and OpenTelemetry providers through options.

License

The license will be defined before the first stable release.