This library is compatible with Go 1.22+
Please refer to CHANGELOG.md if you encounter breaking changes.
magnus-sdk is a thin, type-safe HTTP client for the Magnus Remote API.
It supports:
- Running workflows (Remote Workflow Execution v2)
- Retrieving workflow history and recent history
- Searching workflows
- Locking/unlocking workflows
- Generating signed URLs
JWT is carried in the request body under the jwt field (not in headers). The SDK can mint and inject this token automatically when configured with a signer.
go get github.com/viant/magnus-sdkMagnus expects a signed JWT in the request body (jwt). This SDK integrates with github.com/viant/scy to sign tokens using RSA private keys (e.g., Google Service Account private_key PEM).
You can either:
- Pass a token explicitly to calls that accept it; or
- Configure a per-client signer and (optionally) default claims/TTL to auto-inject
jwtinto supported requests.
package main
import (
"context"
"time"
"github.com/viant/magnus-sdk"
"github.com/viant/scy"
)
func main() {
ctx := context.Background()
// Load RSA private key from a scy secret (PEM content)
rsaRes := scy.NewResource(nil, "~/.secret/service_account.pem", "blowfish://default")
client, err := magnus.New(
ctx,
magnus.WithEndpoint("https://magnus.viantinc.com/remote"),
magnus.WithScyRSA(ctx, rsaRes), // load signer once per client
magnus.WithJWTDefaults(time.Hour, map[string]any{"email": "[email protected]"}),
)
if err != nil { panic(err) }
// Run a workflow (auto-signed: jwt injected into body)
params := []magnus.Parameter{{Name: "var_env", Value: "dev"}}
_, err = client.RunWorkflow(ctx, "", "<base64-workflow-id>", true, params, "", false)
if err != nil { panic(err) }
}// Auto-signed (empty jwt) when signer configured
resp, err := client.RunWorkflow(ctx, "", encodedWorkflowID, true, params, "", false)
// Or pass an explicit token
jwt, _ := client.CreateJWT(time.Minute*30, map[string]any{"email": "[email protected]"})
resp, err = client.RunWorkflow(ctx, jwt, encodedWorkflowID, true, params, "", false)Parameters are sent to Magnus as overrides in the configuration.runWorkflow.parameters array:
params := []magnus.Parameter{
{Name: "var_env", Value: "prod"},
{Name: "var_xxxxx", Value: 123},
{Name: "var_username", Value: "john.doe"},
}// Auto-signed (empty jwt)
hist, err := client.GetHistory(ctx, "", workflowID, historyID)recent, err := client.GetRecentHistory(ctx, workflowID, 7, 100, "")filters := &magnus.SearchFilters{UserID: "[email protected]", IsEnabled: ptr(true)}
found, err := client.SearchWorkflows(ctx, filters, "summary", 50, "")_, err := client.LockWorkflows(ctx, []string{"wf1", "wf2"}, "maintenance window")
_, err = client.UnlockWorkflows(ctx, []string{"wf1", "wf2"}, "done")signed, err := client.SignUrls(ctx, []string{"gs://bucket/object"}, 3600)WithEndpoint(string): Set Magnus Remote API endpoint (defaults tohttp://magnus.viantinc.com/remote).WithHTTPClient(*http.Client): Provide a custom HTTP client.WithSigner(*jwtSigner.Service): Use a pre-initialized scy JWT signer (enforced once per client).WithScyRSA(ctx, *scy.Resource): Initialize an RSA signer from a scy resource (enforced once per client).WithJWTDefaults(ttl time.Duration, claims any): Default TTL/claims for auto-signed requests whenjwtis not provided.
The source code is made available under the terms of the Apache License, Version 2, as stated in the file LICENSE.
Note: Magnus expects JWT in the request body under the jwt field. The SDK handles this automatically when configured with a signer.