switchboard/core
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Releases 9 Wiki Activity

Feat v0.9.7 workflow starlark write (#81)
All checks were successful
CI/CD / detect-changes (push) Successful in 4s
Details
CI/CD / test-frontend (push) Has been skipped
Details
CI/CD / test-runners (push) Has been skipped
Details
CI/CD / e2e-smoke (push) Has been skipped
Details
CI/CD / test-go-pg (push) Successful in 2m49s
Details
CI/CD / test-sqlite (push) Successful in 3m2s
Details
CI/CD / build-and-deploy (push) Successful in 29s
Details

Browse Source 
Co-authored-by: Jeffrey Smith <jasafpro@gmail.com>
Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>
This commit was merged in pull request #81.
This commit is contained in:
Jeffrey Smith
2026-04-03 18:30:10 +00:00
committed by xcaliber
parent ac7286f83b
commit 42b864376c
7 changed files with 512 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
server/sandbox/workflow_module.go
View File

@@ -6,12 +6,13 @@ package sandbox
// manage instances, and programmatically advance workflow stages.
//
// Starlark API:
// wf = workflow.get_definition(workflow_id) # returns dict
// inst = workflow.get_instance(instance_id) # returns dict
// inst = workflow.start(workflow_id, data={}) # start new instance
// inst = workflow.advance(instance_id, data={}) # advance to next stage
// workflow.cancel(instance_id) # cancel instance
// instances = workflow.list_instances(workflow_id) # list instances
// wf = workflow.get_definition(workflow_id) # returns dict
// inst = workflow.get_instance(instance_id) # returns dict
// instances = workflow.list_instances(workflow_id) # list instances
// inst = workflow.start(workflow_id, data={}) # start new instance
// inst = workflow.advance(instance_id, data={}) # advance to next stage
// workflow.cancel(instance_id) # cancel instance
// signoff = workflow.submit_signoff(instance_id, decision, comment="") # submit signoff
import (
"context"
@@ -21,21 +22,37 @@ import (
"go.starlark.net/starlark"
"go.starlark.net/starlarkstruct"
"armature/models"
"armature/store"
)
// WorkflowEngine is the subset of the workflow engine needed by Starlark
// write operations. Defined here (not in the workflow package) to avoid
// circular imports — workflow imports sandbox for the Runner.
type WorkflowEngine interface {
Start(ctx context.Context, workflowID string, initialData json.RawMessage, userID string) (*models.WorkflowInstance, error)
Advance(ctx context.Context, instanceID string, stageData json.RawMessage, userID string) (*models.WorkflowInstance, error)
Cancel(ctx context.Context, instanceID string, userID string) error
SubmitSignoff(ctx context.Context, instanceID, userID, decision, comment string) (*models.WorkflowSignoff, error)
}
// BuildWorkflowModule creates the "workflow" Starlark module for a package.
// Requires the workflow.access permission.
//
// Mutating operations (start/advance/cancel) are available via HTTP API;
// Starlark builtins for them will be added when the engine interface is
// extracted to a shared package to avoid circular imports.
func BuildWorkflowModule(ctx context.Context, stores store.Stores) *starlarkstruct.Module {
return MakeModule("workflow", starlark.StringDict{
// Read operations use stores directly. Write operations delegate to the
// WorkflowEngine interface (engine may be nil if not wired — write builtins
// return an error in that case).
func BuildWorkflowModule(ctx context.Context, stores store.Stores, engine WorkflowEngine, rc *RunContext) *starlarkstruct.Module {
members := starlark.StringDict{
"get_definition": starlark.NewBuiltin("workflow.get_definition", workflowGetDef(ctx, stores)),
"get_instance": starlark.NewBuiltin("workflow.get_instance", workflowGetInstance(ctx, stores)),
"list_instances": starlark.NewBuiltin("workflow.list_instances", workflowListInstances(ctx, stores)),
})
"start": starlark.NewBuiltin("workflow.start", workflowStart(ctx, engine, rc)),
"advance": starlark.NewBuiltin("workflow.advance", workflowAdvance(ctx, engine, rc)),
"cancel": starlark.NewBuiltin("workflow.cancel", workflowCancel(ctx, engine, rc)),
"submit_signoff": starlark.NewBuiltin("workflow.submit_signoff", workflowSubmitSignoff(ctx, engine, rc)),
}
return MakeModule("workflow", members)
}
func workflowGetDef(ctx context.Context, stores store.Stores) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
@@ -98,35 +115,51 @@ func workflowGetInstance(ctx context.Context, stores store.Stores) func(*starlar
if err != nil {
return starlark.None, fmt.Errorf("workflow.get_instance: %w", err)
}
d := starlark.NewDict(8)
d.SetKey(starlark.String("id"), starlark.String(inst.ID))
d.SetKey(starlark.String("workflow_id"), starlark.String(inst.WorkflowID))
d.SetKey(starlark.String("workflow_version"), starlark.MakeInt(inst.WorkflowVersion))
d.SetKey(starlark.String("current_stage"), starlark.String(inst.CurrentStage))
d.SetKey(starlark.String("status"), starlark.String(inst.Status))
d.SetKey(starlark.String("started_by"), starlark.String(inst.StartedBy))
// Parse stage_data into Starlark dict
var dataMap map[string]interface{}
if json.Unmarshal(inst.StageData, &dataMap) == nil {
starlarkData := starlark.NewDict(len(dataMap))
for k, v := range dataMap {
starlarkData.SetKey(starlark.String(k), GoToStarlark(v))
}
d.SetKey(starlark.String("stage_data"), starlarkData)
} else {
d.SetKey(starlark.String("stage_data"), starlark.NewDict(0))
}
if inst.EntryToken != nil {
d.SetKey(starlark.String("entry_token"), starlark.String(*inst.EntryToken))
}
return d, nil
return instanceToDict(inst), nil
}
}
// instanceToDict converts a WorkflowInstance to a Starlark dict.
func instanceToDict(inst *models.WorkflowInstance) *starlark.Dict {
d := starlark.NewDict(8)
d.SetKey(starlark.String("id"), starlark.String(inst.ID))
d.SetKey(starlark.String("workflow_id"), starlark.String(inst.WorkflowID))
d.SetKey(starlark.String("workflow_version"), starlark.MakeInt(inst.WorkflowVersion))
d.SetKey(starlark.String("current_stage"), starlark.String(inst.CurrentStage))
d.SetKey(starlark.String("status"), starlark.String(inst.Status))
d.SetKey(starlark.String("started_by"), starlark.String(inst.StartedBy))
// Parse stage_data into Starlark dict
var dataMap map[string]interface{}
if json.Unmarshal(inst.StageData, &dataMap) == nil {
starlarkData := starlark.NewDict(len(dataMap))
for k, v := range dataMap {
starlarkData.SetKey(starlark.String(k), GoToStarlark(v))
}
d.SetKey(starlark.String("stage_data"), starlarkData)
} else {
d.SetKey(starlark.String("stage_data"), starlark.NewDict(0))
}
if inst.EntryToken != nil {
d.SetKey(starlark.String("entry_token"), starlark.String(*inst.EntryToken))
}
return d
}
// signoffToDict converts a WorkflowSignoff to a Starlark dict.
func signoffToDict(s *models.WorkflowSignoff) *starlark.Dict {
d := starlark.NewDict(7)
d.SetKey(starlark.String("id"), starlark.String(s.ID))
d.SetKey(starlark.String("instance_id"), starlark.String(s.InstanceID))
d.SetKey(starlark.String("stage"), starlark.String(s.Stage))
d.SetKey(starlark.String("user_id"), starlark.String(s.UserID))
d.SetKey(starlark.String("decision"), starlark.String(s.Decision))
d.SetKey(starlark.String("comment"), starlark.String(s.Comment))
d.SetKey(starlark.String("created_at"), starlark.String(s.CreatedAt.Format("2006-01-02T15:04:05Z07:00")))
return d
}
func workflowListInstances(ctx context.Context, stores store.Stores) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
var workflowID string
@@ -155,5 +188,113 @@ func workflowListInstances(ctx context.Context, stores store.Stores) func(*starl
}
}
// workflowRoute routes the workflow to a named stage.
// Starlark: workflow.route(instance_id, target_stage, reason)
// ── Instance Write API ──────────────
// workflowWriteGuard checks that the engine and user context are available.
func workflowWriteGuard(engine WorkflowEngine, rc *RunContext) error {
if engine == nil {
return fmt.Errorf("workflow engine not available")
}
if rc == nil || rc.UserID == "" {
return fmt.Errorf("workflow write operations require an authenticated user context")
}
return nil
}
// dictToJSON converts a Starlark dict to json.RawMessage.
func dictToJSON(d *starlark.Dict) (json.RawMessage, error) {
m := DictToMap(d)
b, err := json.Marshal(m)
if err != nil {
return nil, err
}
return json.RawMessage(b), nil
}
func workflowStart(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
var workflowID string
data := starlark.NewDict(0)
if err := starlark.UnpackArgs("workflow.start", args, kwargs,
"workflow_id", &workflowID,
"data?", &data,
); err != nil {
return nil, err
}
if err := workflowWriteGuard(engine, rc); err != nil {
return nil, fmt.Errorf("workflow.start: %w", err)
}
dataJSON, err := dictToJSON(data)
if err != nil {
return nil, fmt.Errorf("workflow.start: marshal data: %w", err)
}
inst, err := engine.Start(ctx, workflowID, dataJSON, rc.UserID)
if err != nil {
return nil, fmt.Errorf("workflow.start: %w", err)
}
return instanceToDict(inst), nil
}
}
func workflowAdvance(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
var instanceID string
data := starlark.NewDict(0)
if err := starlark.UnpackArgs("workflow.advance", args, kwargs,
"instance_id", &instanceID,
"data?", &data,
); err != nil {
return nil, err
}
if err := workflowWriteGuard(engine, rc); err != nil {
return nil, fmt.Errorf("workflow.advance: %w", err)
}
dataJSON, err := dictToJSON(data)
if err != nil {
return nil, fmt.Errorf("workflow.advance: marshal data: %w", err)
}
inst, err := engine.Advance(ctx, instanceID, dataJSON, rc.UserID)
if err != nil {
return nil, fmt.Errorf("workflow.advance: %w", err)
}
return instanceToDict(inst), nil
}
}
func workflowCancel(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
var instanceID string
if err := starlark.UnpackPositionalArgs("workflow.cancel", args, kwargs, 1, &instanceID); err != nil {
return nil, err
}
if err := workflowWriteGuard(engine, rc); err != nil {
return nil, fmt.Errorf("workflow.cancel: %w", err)
}
if err := engine.Cancel(ctx, instanceID, rc.UserID); err != nil {
return nil, fmt.Errorf("workflow.cancel: %w", err)
}
return starlark.None, nil
}
}
func workflowSubmitSignoff(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
var instanceID, decision string
comment := ""
if err := starlark.UnpackArgs("workflow.submit_signoff", args, kwargs,
"instance_id", &instanceID,
"decision", &decision,
"comment?", &comment,
); err != nil {
return nil, err
}
if err := workflowWriteGuard(engine, rc); err != nil {
return nil, fmt.Errorf("workflow.submit_signoff: %w", err)
}
signoff, err := engine.SubmitSignoff(ctx, instanceID, rc.UserID, decision, comment)
if err != nil {
return nil, fmt.Errorf("workflow.submit_signoff: %w", err)
}
return signoffToDict(signoff), nil
}
}