Accessing Worker Metadata

Golem workers can access their own and other worker's metadata.

In Go the worker metadata accessing functions have idiomatic Go wrappers in the Golem Go SDK.

Worker Metadata

Worker metadata is defined as the following types in the golemhost package:

type ComponentID uuid.UUID
 
type WorkerID struct {
	ComponentID ComponentID
	WorkerName  string
}
 
type WorkerMetadataEnvVar struct {
	Name  string
	Value string
}
 
type WorkerStatus int
 
const (
	WorkerStatusRunning = iota
	WorkerStatusIdle
	WorkerStatusSuspended
	WorkerStatusInterrupted
	WorkerStatusRetrying
	WorkerStatusFailed
	WorkerStatusExited
)
 
type WorkerMetadata struct {
	WorkerId         WorkerID
	Args             []string
	Env              []WorkerMetadataEnvVar
	Status           WorkerStatus
	ComponentVersion uint64
	RetryCount       uint64
}

Get Self Metadata

To access the metadata for the currently running worker use the golemhost.GetSelfMetadata function, which returns golemhost.WorkerMetadata:

import (
	"fmt"
 
	"github.com/golemcloud/golem-go/golemhost"
)
 
workerMetadata := golemhost.GetSelfMetadata()
fmt.Println(workerMetadata.WorkerId.WorkerName)

Get Other Worker's Metadata

Other worker's metadata can be accessed by using the golemhost.GetWorkerMetadata functions, which expects a golemhost.WorkerID, and returns *golemhost.WorkerMetadata:

import (
	"fmt"
 
	"github.com/google/uuid"
 
	"github.com/golemcloud/golem-go/golemhost"
)
 
workerMetadata := golemhost.GetWorkerMetadata(
	golemhost.WorkerID{
		ComponentID: golemhost.ComponentID(uuid.MustParse("d6520ae9-33c9-47e2-8fe1-0da0e6e568ac")),
		WorkerName:  "worker-1",
	},
)
if workerMetadata != nil {
	fmt.Printf("Worker status: %d\n", workerMetadata.Status)
} else {
	fmt.Printf("Worker not found")
}

Enumerate workers

Worker enumeration is a feature of Golem available both through the public HTTP API and using the WIT interfaces, which have idiomatic Go wrappers in the SDK.

⚠️

Enumerating workers of a component is a slow operation and should not be used as part of the application logic.

The following example demonstrates how to enumerate workers by using some filters:

import (
)

// returns []golemhost.WorkerMetadata
results := golemhost.GetWorkers(
	golemhost.ComponentID(uuid.New()),
	&golemhost.WorkerAnyFilter{
		Filters: []golemhost.WorkerAllFilter{
			{
				Filters: []golemhost.WorkerFilter{
					{
						Name:           ptr.New("worker name"),
						NameComparator: golemhost.StringFilterComparatorLike,
					},
					{
						CreatedAt:           ptr.New(time.Now()),
						CreatedAtComparator: golemhost.FilterComparatorLessEqual,
					},
					{
						Version:           ptr.New[uint64](10),
						VersionComparator: golemhost.FilterComparatorNotEqual,
					},
					{
						Status:           ptr.New[golemhost.WorkerStatus](golemhost.WorkerStatusFailed),
						StatusComparator: golemhost.FilterComparatorEqual,
					},
					{
						Env: &golemhost.WorkerEnvFilter{
							Name:  "ENV_VAR",
							Value: "ENV_VAR_VALUE",
						},
						EnvComparator: golemhost.StringFilterComparatorEqual,
					},
				},
			},
		},
	},
)

Generate an idempotency key

Golem provides a function to generate an idempotency key (a UUID) which can be passed to external systems to ensure that the same request is not processed multiple times.

It is guaranteed that this idempotency key will always be the same (per occurrence) even if the worker is restarted due to a crash.

To generate and access an idempotency key use the golemhost.GenerateIdempotencyKey functions:

import (
	"github.com/google/uuid"

	"github.com/golemcloud/golem-go/golemhost"
)

result := golemhost.GenerateIdempotencyKey() // returns uuid.UUID

Promises Updating Workers