helvethink/infrahub-go-sdk repository overview

⁠Infrahub Go SDK

An idiomatic Go client and command-line tool for Infrahub⁠, inspired by the official Python SDK.

⁠Install

go get github.com/Helvethink/infrahub-go-sdk

⁠Client

client, err := infrahub.NewClient(
    "https://infrahub.example.com",
    infrahub.WithAPIToken(os.Getenv("INFRAHUB_API_TOKEN")),
    infrahub.WithDefaultBranch("main"),
)
if err != nil {
    log.Fatal(err)
}

branches, err := client.Branches.List(context.Background())

All network operations accept context.Context. A client is safe for concurrent use, and branch selection is request-scoped.

⁠Packages

• infrahub: client facade and configuration
• pkg/batch: generic bounded concurrent execution
• pkg/api: low-level HTTP and GraphQL protocol
• pkg/automation: Go-native transforms, generators and checks
• pkg/branch: branch lifecycle and types
• pkg/diff: branch diff summaries and complete trees
• pkg/schema: schema discovery, validation, and loading
• pkg/task: background-task filtering and polling
• pkg/traversal: graph paths and reachable nodes
• pkg/config: strict TOML and environment configuration
• pkg/node: generic operations for schema-defined objects
• pkg/objectstore: stored objects and text-file retrieval
• pkg/repository: repository discovery and commit tracking
• pkg/resourcepool: IP address/prefix allocation and utilization
• pkg/tracking: request trackers and group collection
• cmd/infrahubctl: executable entry point
• internal/cli: testable, non-public CLI implementation

Most applications should import only the root package. Packages under pkg/ are available for deliberate advanced use; implementation details remain under internal/.

See the Python SDK porting map⁠ for implemented and planned capabilities.

⁠Development

make check
make race
make build

make check verifies formatting, runs go vet, runs golangci-lint, and executes all unit and facade tests. This check is mandatory after adding a feature.

⁠CLI

Build the command with make build, or install it directly:

go install github.com/Helvethink/infrahub-go-sdk/cmd/infrahubctl@latest

Configuration uses flags or environment variables:

export INFRAHUB_ADDRESS=https://infrahub.example.com
export INFRAHUB_API_TOKEN=...

infrahubctl branch list
infrahubctl branch create --description "SDK work" sdk-work
infrahubctl object validate objects/
infrahubctl object load objects/ --branch sdk-work
infrahubctl task list --state running --limit 10
infrahubctl repository list
infrahubctl schema graphql > schema.graphql
printf 'query { Branch { name } }' | infrahubctl graphql

Run infrahubctl help for the complete command list.

Structured zap logs are written to stderr and never mixed with JSON results on stdout. Set --log-level info or INFRAHUB_LOG_LEVEL=info to log command lifecycle events; the default level is error.

TOML configuration is also supported from the platform user configuration directory, INFRAHUB_CONFIG, INFRAHUBCTL_CONFIG, or -config. See the configuration guide⁠ for the file format and precedence rules.

⁠Dynamic GraphQL

Infrahub generates a GraphQL schema for each data schema and branch. Use Execute for arbitrary queries:

var result struct {
    Tags []struct {
        ID string `json:"id"`
    } `json:"BuiltinTag"`
}

err := client.Execute(ctx, infrahub.GraphQLRequest{
    Query: `query Tags { BuiltinTag { id } }`,
    OperationName: "Tags",
    Branch: "main",
}, &result)

If a GraphQL response contains both data and errors, data is decoded and the returned error can be inspected with errors.As as *infrahub.GraphQLError.

⁠Dynamic nodes

tag, err := client.Nodes.Create(ctx, "BuiltinTag", map[string]any{
    "name":        map[string]any{"value": "staging"},
    "description": map[string]any{"value": "Staging resources"},
}, "main")

Dynamic filters and nested selections are available through client.Nodes.Query. See the dynamic query guide⁠.

⁠Repositories

repositories, err := client.Repositories.List(ctx, infrahub.RepositoryListOptions{
    Branches: []string{"main", "staging"},
})

Repository discovery aggregates commits and internal status across branches. Commit updates are also supported. See the repository guide⁠.

⁠Tracking

group, err := tracking.NewGroup(tracking.GroupOptions{Identifier: "inventory-import"})
ctx = group.Context(tracking.WithTracker(ctx, "inventory-import"))

_, err = client.Nodes.List(ctx, "BuiltinTag", 0, 100, "main")
result, err := group.Save(ctx, client)

Tracking is request-scoped and safe for concurrent workflows. See the tracking and group-context guide⁠.

⁠Object and file storage

uploaded, err := client.ObjectStore.Upload(ctx, "generated configuration")
content, err := client.ObjectStore.Get(ctx, uploaded.Identifier)
file, err := client.ObjectStore.GetFileByID(ctx, nodeID)

Stored objects and text-file endpoints preserve base paths, escape identifiers, and honor response-size limits. See the object-store guide⁠.

⁠Tasks

tasks, err := client.Tasks.All(ctx, infrahub.TaskListOptions{
    Filter: infrahub.TaskFilter{States: []infrahub.TaskState{
        infrahub.TaskStateRunning,
    }},
})

task, err := client.Tasks.Wait(ctx, taskID, time.Second)

Task filters, logs, related nodes, pagination and cancellation-aware polling are supported. See the tasks guide⁠.

⁠Batches

results, err := batch.Map(ctx, nodeIDs, func(ctx context.Context, id string) (*infrahub.Node, error) {
    return client.Nodes.GetByID(ctx, "BuiltinDevice", id, "main")
}, batch.Options{Concurrency: 5})

Batch results retain input indexes and support fail-fast or per-result error collection. See the batches guide⁠.

⁠IP address and prefix pools

prefixLength := 32
address, err := client.ResourcePools.AllocateAddress(ctx, infrahub.ResourcePoolAddressOptions{
    PoolID:       poolID,
    Identifier:   "loopback-edge-01",
    PrefixLength: &prefixLength,
    AddressKind:  "IpamIPAddress",
    Branch:       "main",
})

Prefix allocation, allocation history and utilization are also supported. See the resource-pool guide⁠.

⁠Diffs

tree, err := client.Diffs.Tree(ctx, infrahub.DiffOptions{
    Branch: "feature/inventory",
})

Node summaries, complete metadata, time ranges, attributes, relationships and peer changes are supported. See the diff guide⁠.

⁠Graph traversal

paths, err := client.Traversal.Paths(ctx, infrahub.TraversalPathsOptions{
    SourceID:      sourceID,
    DestinationID: destinationID,
    Branch:        "main",
})

Path existence, filters, point-in-time traversal and reachable-node discovery are supported on Infrahub 1.10+. See the graph traversal guide⁠.

⁠Automation extensions

result, err := client.Automation.RunCheck(ctx, infrahub.AutomationRunOptions{
    Query: infrahub.AutomationQueryOptions{Name: "check_input", Branch: "main"},
}, func(ctx context.Context, data map[string]any, report *infrahub.AutomationReporter) error {
    report.Error("management address is missing", nodeID, "DcimDevice")
    return nil
})

Transforms, idempotent generators and structured checks are implemented as compiled Go extension points. See the automation guide⁠.

⁠Current scope

• GraphQL transport, authentication, trackers, branch/time routing, and partial errors
• Branch list/get/create/delete/rebase/validate/merge and diff data
• Schema fetch, SDL export, validation, and loading
• Generic node create/update/delete
• Generic node list/get-by-ID/get-by-HFID with offset pagination
• Repository discovery across branches and protected commit updates
• Request-scoped tracker overrides and concurrent tracking groups
• Stored object upload/download and text-file retrieval by storage ID, node ID, or HFID
• Background-task filtering, pagination, lookup, counts, logs and polling
• Generic bounded batches with cancellation and configurable error collection
• IP address/prefix allocation, allocation history and pool utilization
• Branch diff summaries and complete diff trees
• Graph path traversal, connectivity checks and reachable-node discovery
• Go-native transforms, tracked generators and structured checks

Planned ports include schema-aware custom-field query construction, graph traversal, diffs, IP resource allocation, object/file storage, tasks, batches, and tracking. Python-only runtime features such as Jinja transforms and pytest plugins will not be copied into the core Go library.