blokctl 1.3.0 → 1.4.1

package/dist/scaffold-repo/sdks/go/types.go

@@ -0,0 +1,295 @@
+// Package blok provides the Blok blok runtime SDK for Go.
+//
+// This SDK enables building workflow nodes that integrate with the Blok
+// orchestration framework. Nodes communicate via HTTP (POST /execute, GET /health)
+// and can be deployed as Docker containers.
+package blok
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+// Context represents the workflow execution context passed between nodes.
+type Context struct {
+	ID           string                 `json:"id"`
+	WorkflowName string                 `json:"workflow_name"`
+	WorkflowPath string                 `json:"workflow_path"`
+	Request      Request                `json:"request"`
+	Response     Response               `json:"response"`
+	Vars         map[string]interface{} `json:"vars"`
+	Env          map[string]string      `json:"env"`
+
+	// streamLog, when set, sinks log events into the per-call gRPC
+	// ExecuteStream channel. Set by `BlokNodeRuntime.ExecuteStream`
+	// for the duration of one streaming call; unset (nil) on the
+	// unary Execute path. Handlers should NOT call this directly —
+	// they call the public `Context.StreamLog` shim, which is
+	// always safe to call (no-op when streaming is off).
+	//
+	// Type signature is the public StreamLogEntry struct so handlers can
+	// import the type cleanly without reaching into the gRPC
+	// internals.
+	//
+	// Phase 5 follow-up per master plan §17.
+	streamLog func(StreamLogEntry)
+}
+
+// StreamLogEntry is a single log event emitted by a node handler. Carries the
+// level, message, and optional structured attributes. Handed to
+// `Context.StreamLog`; if streaming is enabled the runner receives a
+// `LogLine` proto for each entry in real time.
+type StreamLogEntry struct {
+	Level   string            // "debug" | "info" | "warn" | "error" (lowercase, free-form)
+	Message string            // human-readable message
+	Attrs   map[string]string // optional structured attributes
+}
+
+// StreamLog emits a real-time log event to the runner's ExecuteStream
+// channel. No-op on the unary Execute path (when the call is unary,
+// `streamLog` is nil and StreamLog returns immediately). Safe to call
+// from any goroutine — the underlying channel is unbuffered-but-
+// non-blocking via a `select { default }` drop policy in the
+// servicer's send loop, so a flood of logs from a busy handler can't
+// stall the request thread.
+//
+// Recommended call style:
+//
+//	ctx.StreamLog(blok.StreamLogEntry{
+//	    Level:   "info",
+//	    Message: fmt.Sprintf("Processing batch %d", i),
+//	    Attrs:   map[string]string{"batch_size": fmt.Sprint(len(batch))},
+//	})
+func (c *Context) StreamLog(entry StreamLogEntry) {
+	if c.streamLog != nil {
+		c.streamLog(entry)
+	}
+}
+
+// setStreamLog wires the per-call sink into the context. Internal
+// helper used by `BlokNodeRuntime.ExecuteStream`. Cleared when the
+// streaming call finishes so a leaked context can't accidentally
+// publish to a closed channel.
+func (c *Context) setStreamLog(sink func(StreamLogEntry)) {
+	c.streamLog = sink
+}
+
+// SetVar stores a variable in the context for downstream nodes.
+func (c *Context) SetVar(key string, value interface{}) {
+	if c.Vars == nil {
+		c.Vars = make(map[string]interface{})
+	}
+	c.Vars[key] = value
+}
+
+// GetVar retrieves a variable from the context.
+func (c *Context) GetVar(key string) (interface{}, bool) {
+	if c.Vars == nil {
+		return nil, false
+	}
+	v, ok := c.Vars[key]
+	return v, ok
+}
+
+// GetVarString retrieves a string variable from the context.
+func (c *Context) GetVarString(key string) string {
+	v, ok := c.GetVar(key)
+	if !ok {
+		return ""
+	}
+	s, _ := v.(string)
+	return s
+}
+
+// Request represents the incoming HTTP request data.
+type Request struct {
+	Body    interface{}       `json:"body"`
+	Headers map[string]string `json:"headers"`
+	Params  map[string]string `json:"params"`
+	Query   map[string]string `json:"query"`
+	Method  string            `json:"method"`
+	URL     string            `json:"url"`
+	Cookies map[string]string `json:"cookies"`
+	BaseURL string            `json:"baseUrl"`
+}
+
+// BodyAs unmarshals the request body into the target struct.
+func (r *Request) BodyAs(target interface{}) error {
+	bytes, err := json.Marshal(r.Body)
+	if err != nil {
+		return fmt.Errorf("failed to marshal body: %w", err)
+	}
+	return json.Unmarshal(bytes, target)
+}
+
+// BodyMap returns the request body as a map, or nil if not a map.
+func (r *Request) BodyMap() map[string]interface{} {
+	m, _ := r.Body.(map[string]interface{})
+	return m
+}
+
+// Response represents the workflow response.
+type Response struct {
+	Data        interface{} `json:"data"`
+	ContentType string      `json:"contentType"`
+	Success     bool        `json:"success"`
+	Error       interface{} `json:"error"`
+}
+
+// NodeConfig represents node-specific configuration from the runner.
+type NodeConfig struct {
+	Name   string                 `json:"name"`
+	Type   string                 `json:"type,omitempty"`
+	Path   string                 `json:"path,omitempty"`
+	Config map[string]interface{} `json:"config"`
+}
+
+// GetConfigString retrieves a string config value with a default.
+func (nc *NodeConfig) GetConfigString(key, defaultVal string) string {
+	if nc.Config == nil {
+		return defaultVal
+	}
+	v, ok := nc.Config[key]
+	if !ok {
+		return defaultVal
+	}
+	s, ok := v.(string)
+	if !ok {
+		return defaultVal
+	}
+	return s
+}
+
+// GetConfigInt retrieves an integer config value with a default.
+func (nc *NodeConfig) GetConfigInt(key string, defaultVal int) int {
+	if nc.Config == nil {
+		return defaultVal
+	}
+	v, ok := nc.Config[key]
+	if !ok {
+		return defaultVal
+	}
+	switch n := v.(type) {
+	case float64:
+		return int(n)
+	case int:
+		return n
+	default:
+		return defaultVal
+	}
+}
+
+// GetConfigBool retrieves a boolean config value with a default.
+func (nc *NodeConfig) GetConfigBool(key string, defaultVal bool) bool {
+	if nc.Config == nil {
+		return defaultVal
+	}
+	v, ok := nc.Config[key]
+	if !ok {
+		return defaultVal
+	}
+	b, ok := v.(bool)
+	if !ok {
+		return defaultVal
+	}
+	return b
+}
+
+// ExecutionRequest is the request received from the Blok runner.
+type ExecutionRequest struct {
+	Node    NodeConfig `json:"node"`
+	Context Context    `json:"context"`
+}
+
+// ExecutionResult is the response returned to the Blok runner.
+type ExecutionResult struct {
+	Success bool                   `json:"success"`
+	Data    interface{}            `json:"data"`
+	Errors  interface{}            `json:"errors"`
+	Logs    []string               `json:"logs,omitempty"`
+	Metrics *ExecutionMetrics      `json:"metrics,omitempty"`
+	Vars    map[string]interface{} `json:"vars,omitempty"`
+}
+
+// WithVars attaches context variables to the result.
+func (r *ExecutionResult) WithVars(vars map[string]interface{}) *ExecutionResult {
+	r.Vars = vars
+	return r
+}
+
+// NewSuccessResult creates a successful execution result.
+func NewSuccessResult(data interface{}) *ExecutionResult {
+	return &ExecutionResult{
+		Success: true,
+		Data:    data,
+		Errors:  nil,
+	}
+}
+
+// NewErrorResult creates a failed execution result.
+func NewErrorResult(message string) *ExecutionResult {
+	return &ExecutionResult{
+		Success: false,
+		Data:    nil,
+		Errors: map[string]string{
+			"message": message,
+		},
+	}
+}
+
+// NewErrorResultWithDetails creates a failed execution result with additional details.
+func NewErrorResultWithDetails(message string, details map[string]interface{}) *ExecutionResult {
+	return &ExecutionResult{
+		Success: false,
+		Data:    nil,
+		Errors: map[string]interface{}{
+			"message": message,
+			"details": details,
+		},
+	}
+}
+
+// WithLogs adds log entries to the result.
+func (r *ExecutionResult) WithLogs(logs []string) *ExecutionResult {
+	r.Logs = logs
+	return r
+}
+
+// WithMetrics adds execution metrics to the result.
+func (r *ExecutionResult) WithMetrics(metrics *ExecutionMetrics) *ExecutionResult {
+	r.Metrics = metrics
+	return r
+}
+
+// ExecutionMetrics captures performance metrics for a node execution.
+type ExecutionMetrics struct {
+	DurationMs  *float64 `json:"duration_ms,omitempty"`
+	CpuMs       *float64 `json:"cpu_ms,omitempty"`
+	MemoryBytes *uint64  `json:"memory_bytes,omitempty"`
+}
+
+// HealthStatus represents the health status of the runtime.
+type HealthStatus struct {
+	Status      string   `json:"status"`
+	Version     string   `json:"version"`
+	NodesLoaded []string `json:"nodes_loaded"`
+}
+
+// ParseBody is a helper to unmarshal a generic body into a typed struct.
+func ParseBody(body interface{}, target interface{}) error {
+	bytes, err := json.Marshal(body)
+	if err != nil {
+		return fmt.Errorf("failed to marshal body: %w", err)
+	}
+	return json.Unmarshal(bytes, target)
+}
+
+// Float64Ptr returns a pointer to a float64 value.
+func Float64Ptr(v float64) *float64 {
+	return &v
+}
+
+// Uint64Ptr returns a pointer to a uint64 value.
+func Uint64Ptr(v uint64) *uint64 {
+	return &v
+}

package/dist/scaffold-repo/sdks/go/types_test.go

@@ -0,0 +1,251 @@
+package blok
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestContextJSON(t *testing.T) {
+	ctx := Context{
+		ID:           "test-123",
+		WorkflowName: "test-workflow",
+		WorkflowPath: "/workflows/test",
+		Request: Request{
+			Body:    map[string]interface{}{"key": "value"},
+			Headers: map[string]string{"Content-Type": "application/json"},
+			Params:  map[string]string{"id": "1"},
+			Query:   map[string]string{"page": "1"},
+			Method:  "POST",
+			URL:     "/api/test",
+			Cookies: map[string]string{},
+			BaseURL: "http://localhost:8080",
+		},
+		Response: Response{
+			Success: true,
+			Data:    nil,
+		},
+		Vars: map[string]interface{}{},
+		Env:  map[string]string{"NODE_ENV": "test"},
+	}
+
+	// Marshal to JSON
+	data, err := json.Marshal(ctx)
+	if err != nil {
+		t.Fatalf("failed to marshal context: %v", err)
+	}
+
+	// Unmarshal back
+	var restored Context
+	if err := json.Unmarshal(data, &restored); err != nil {
+		t.Fatalf("failed to unmarshal context: %v", err)
+	}
+
+	if restored.ID != ctx.ID {
+		t.Errorf("ID mismatch: got %q, want %q", restored.ID, ctx.ID)
+	}
+	if restored.WorkflowName != ctx.WorkflowName {
+		t.Errorf("WorkflowName mismatch: got %q, want %q", restored.WorkflowName, ctx.WorkflowName)
+	}
+	if restored.Request.Method != ctx.Request.Method {
+		t.Errorf("Method mismatch: got %q, want %q", restored.Request.Method, ctx.Request.Method)
+	}
+	if restored.Request.BaseURL != ctx.Request.BaseURL {
+		t.Errorf("BaseURL mismatch: got %q, want %q", restored.Request.BaseURL, ctx.Request.BaseURL)
+	}
+}
+
+func TestContextSetGetVar(t *testing.T) {
+	ctx := &Context{}
+
+	// Set var on nil map
+	ctx.SetVar("key", "value")
+	v, ok := ctx.GetVar("key")
+	if !ok || v != "value" {
+		t.Errorf("expected 'value', got %v (ok=%v)", v, ok)
+	}
+
+	// Get nonexistent
+	_, ok = ctx.GetVar("missing")
+	if ok {
+		t.Error("expected ok=false for missing key")
+	}
+
+	// GetVarString
+	ctx.SetVar("name", "test")
+	s := ctx.GetVarString("name")
+	if s != "test" {
+		t.Errorf("expected 'test', got %q", s)
+	}
+
+	// GetVarString missing returns ""
+	s = ctx.GetVarString("missing")
+	if s != "" {
+		t.Errorf("expected empty string, got %q", s)
+	}
+}
+
+func TestRequestBodyAs(t *testing.T) {
+	req := Request{
+		Body: map[string]interface{}{
+			"name": "World",
+			"age":  float64(30),
+		},
+	}
+
+	type bodyType struct {
+		Name string  `json:"name"`
+		Age  float64 `json:"age"`
+	}
+
+	var body bodyType
+	if err := req.BodyAs(&body); err != nil {
+		t.Fatalf("BodyAs failed: %v", err)
+	}
+
+	if body.Name != "World" {
+		t.Errorf("expected 'World', got %q", body.Name)
+	}
+	if body.Age != 30 {
+		t.Errorf("expected 30, got %v", body.Age)
+	}
+}
+
+func TestRequestBodyMap(t *testing.T) {
+	req := Request{
+		Body: map[string]interface{}{"key": "value"},
+	}
+	m := req.BodyMap()
+	if m == nil {
+		t.Fatal("expected non-nil map")
+	}
+	if m["key"] != "value" {
+		t.Errorf("expected 'value', got %v", m["key"])
+	}
+
+	// Non-map body returns nil
+	req.Body = "not a map"
+	m = req.BodyMap()
+	if m != nil {
+		t.Error("expected nil for non-map body")
+	}
+}
+
+func TestNodeConfigHelpers(t *testing.T) {
+	nc := NodeConfig{
+		Name: "test",
+		Config: map[string]interface{}{
+			"prefix":  "Hi",
+			"count":   float64(5),
+			"enabled": true,
+		},
+	}
+
+	if v := nc.GetConfigString("prefix", "default"); v != "Hi" {
+		t.Errorf("expected 'Hi', got %q", v)
+	}
+	if v := nc.GetConfigString("missing", "default"); v != "default" {
+		t.Errorf("expected 'default', got %q", v)
+	}
+
+	if v := nc.GetConfigInt("count", 0); v != 5 {
+		t.Errorf("expected 5, got %d", v)
+	}
+	if v := nc.GetConfigInt("missing", 10); v != 10 {
+		t.Errorf("expected 10, got %d", v)
+	}
+
+	if v := nc.GetConfigBool("enabled", false); !v {
+		t.Error("expected true")
+	}
+	if v := nc.GetConfigBool("missing", false); v {
+		t.Error("expected false for missing key")
+	}
+}
+
+func TestExecutionResultJSON(t *testing.T) {
+	tests := []struct {
+		name   string
+		result *ExecutionResult
+	}{
+		{
+			name:   "success",
+			result: NewSuccessResult(map[string]string{"message": "hello"}),
+		},
+		{
+			name:   "error",
+			result: NewErrorResult("something went wrong"),
+		},
+		{
+			name: "success with metrics",
+			result: NewSuccessResult("data").WithMetrics(&ExecutionMetrics{
+				DurationMs:  Float64Ptr(12.5),
+				MemoryBytes: Uint64Ptr(1024),
+			}),
+		},
+		{
+			name:   "success with logs",
+			result: NewSuccessResult("data").WithLogs([]string{"log1", "log2"}),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			data, err := json.Marshal(tt.result)
+			if err != nil {
+				t.Fatalf("failed to marshal: %v", err)
+			}
+
+			var restored ExecutionResult
+			if err := json.Unmarshal(data, &restored); err != nil {
+				t.Fatalf("failed to unmarshal: %v", err)
+			}
+
+			if restored.Success != tt.result.Success {
+				t.Errorf("Success mismatch: got %v, want %v", restored.Success, tt.result.Success)
+			}
+		})
+	}
+}
+
+func TestHealthStatusJSON(t *testing.T) {
+	health := HealthStatus{
+		Status:      "healthy",
+		Version:     "1.0.0",
+		NodesLoaded: []string{"hello-world", "api-call"},
+	}
+
+	data, err := json.Marshal(health)
+	if err != nil {
+		t.Fatalf("failed to marshal: %v", err)
+	}
+
+	var restored HealthStatus
+	if err := json.Unmarshal(data, &restored); err != nil {
+		t.Fatalf("failed to unmarshal: %v", err)
+	}
+
+	if restored.Status != "healthy" {
+		t.Errorf("expected 'healthy', got %q", restored.Status)
+	}
+	if len(restored.NodesLoaded) != 2 {
+		t.Errorf("expected 2 nodes, got %d", len(restored.NodesLoaded))
+	}
+}
+
+func TestParseBody(t *testing.T) {
+	body := map[string]interface{}{
+		"name": "test",
+	}
+
+	type target struct {
+		Name string `json:"name"`
+	}
+
+	var result target
+	if err := ParseBody(body, &result); err != nil {
+		t.Fatalf("ParseBody failed: %v", err)
+	}
+	if result.Name != "test" {
+		t.Errorf("expected 'test', got %q", result.Name)
+	}
+}