blokctl 1.2.0 → 1.4.0

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

@@ -0,0 +1,207 @@
+package blok
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"time"
+)
+
+// Server is the blok HTTP server that handles execute and health requests.
+type Server struct {
+	registry   *NodeRegistry
+	config     ServerConfig
+	httpServer *http.Server
+}
+
+// NewServer creates a new blok server.
+func NewServer(registry *NodeRegistry, config ServerConfig) *Server {
+	return &Server{
+		registry: registry,
+		config:   config,
+	}
+}
+
+// Start starts the HTTP server and blocks until it is shut down.
+func (s *Server) Start() error {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/execute", s.handleExecute)
+	mux.HandleFunc("/health", s.handleHealth)
+
+	var handler http.Handler = mux
+	if s.config.EnableCORS {
+		handler = s.corsHandler(handler)
+	}
+
+	s.httpServer = &http.Server{
+		Addr:         s.config.Address(),
+		Handler:      handler,
+		ReadTimeout:  time.Duration(s.config.ReadTimeoutSec) * time.Second,
+		WriteTimeout: time.Duration(s.config.WriteTimeoutSec) * time.Second,
+	}
+
+	log.Printf("Blok runtime v%s starting on %s", s.config.Version, s.config.Address())
+	log.Printf("Registered nodes: %v", s.registry.NodeNames())
+
+	return s.httpServer.ListenAndServe()
+}
+
+// Shutdown gracefully shuts down the server.
+func (s *Server) Shutdown() error {
+	if s.httpServer == nil {
+		return nil
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(s.config.ShutdownTimeoutSec)*time.Second)
+	defer cancel()
+	log.Println("Shutting down blok runtime...")
+	return s.httpServer.Shutdown(ctx)
+}
+
+// HTTPServer returns the underlying http.Server for advanced use cases.
+func (s *Server) HTTPServer() *http.Server {
+	return s.httpServer
+}
+
+func (s *Server) handleExecute(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		s.writeJSON(w, http.StatusMethodNotAllowed, &ExecutionResult{
+			Success: false,
+			Errors:  map[string]string{"message": "method not allowed, use POST"},
+		})
+		return
+	}
+
+	var req ExecutionRequest
+	decoder := json.NewDecoder(r.Body)
+	if err := decoder.Decode(&req); err != nil {
+		s.writeJSON(w, http.StatusBadRequest, &ExecutionResult{
+			Success: false,
+			Errors:  map[string]string{"message": fmt.Sprintf("invalid JSON: %v", err)},
+		})
+		return
+	}
+
+	result := s.registry.Execute(&req)
+	s.writeJSON(w, http.StatusOK, result)
+}
+
+func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	health := s.registry.Health(s.config.Version)
+	s.writeJSON(w, http.StatusOK, health)
+}
+
+func (s *Server) writeJSON(w http.ResponseWriter, statusCode int, data interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(statusCode)
+	if err := json.NewEncoder(w).Encode(data); err != nil {
+		log.Printf("Error encoding JSON response: %v", err)
+	}
+}
+
+func (s *Server) corsHandler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
+
+		if r.Method == http.MethodOptions {
+			w.WriteHeader(http.StatusNoContent)
+			return
+		}
+
+		next.ServeHTTP(w, r)
+	})
+}
+
+// ListenAndServe is a convenience function that creates the configured
+// server(s) and serves until shutdown.
+//
+// Honors `cfg.Transport`:
+//   - TransportHTTP (default): HTTP only.
+//   - TransportGRPC: gRPC only on cfg.GRPCPort.
+//   - TransportBoth: HTTP + gRPC in the same process.
+func ListenAndServe(registry *NodeRegistry) error {
+	config := LoadConfigFromEnv()
+	return ListenAndServeWithConfig(registry, config)
+}
+
+// ListenAndServeWithConfig is the same as ListenAndServe but uses the
+// provided config. Useful for tests that want to inject a fixed config.
+func ListenAndServeWithConfig(registry *NodeRegistry, config ServerConfig) error {
+	switch config.Transport {
+	case TransportGRPC:
+		return runGrpcOnly(registry, config)
+	case TransportBoth:
+		return runBoth(registry, config)
+	case TransportHTTP, "":
+		return runHTTPOnly(registry, config)
+	default:
+		return fmt.Errorf("unknown BLOK_TRANSPORT %q (expected http | grpc | both)", config.Transport)
+	}
+}
+
+func runHTTPOnly(registry *NodeRegistry, config ServerConfig) error {
+	server := NewServer(registry, config)
+
+	shutdownCh := SetupGracefulShutdown(func() {
+		if err := server.Shutdown(); err != nil {
+			log.Printf("Error during shutdown: %v", err)
+		}
+	})
+
+	err := server.Start()
+	if err == http.ErrServerClosed {
+		<-shutdownCh
+		return nil
+	}
+	return err
+}
+
+func runGrpcOnly(registry *NodeRegistry, config ServerConfig) error {
+	grpcServer, _, err := StartGrpc(registry, config.Host, config.GRPCPort, GrpcServerOptions{
+		SdkVersion: config.Version,
+	})
+	if err != nil {
+		return err
+	}
+
+	shutdownCh := SetupGracefulShutdown(func() {
+		log.Println("Shutting down gRPC server…")
+		grpcServer.GracefulStop()
+	})
+	<-shutdownCh
+	return nil
+}
+
+func runBoth(registry *NodeRegistry, config ServerConfig) error {
+	grpcServer, _, err := StartGrpc(registry, config.Host, config.GRPCPort, GrpcServerOptions{
+		SdkVersion: config.Version,
+	})
+	if err != nil {
+		return err
+	}
+
+	httpServer := NewServer(registry, config)
+
+	shutdownCh := SetupGracefulShutdown(func() {
+		log.Println("Shutting down gRPC server…")
+		grpcServer.GracefulStop()
+		if shutErr := httpServer.Shutdown(); shutErr != nil {
+			log.Printf("Error during HTTP shutdown: %v", shutErr)
+		}
+	})
+
+	startErr := httpServer.Start()
+	if startErr == http.ErrServerClosed {
+		<-shutdownCh
+		return nil
+	}
+	return startErr
+}

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

@@ -0,0 +1,186 @@
+package blok
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func newTestServer() (*Server, *NodeRegistry) {
+	registry := NewNodeRegistry()
+	registry.Register("test-node", &testNode{
+		returnData: map[string]string{"message": "hello"},
+	})
+
+	config := DefaultConfig()
+	server := NewServer(registry, config)
+	return server, registry
+}
+
+func TestHandleExecuteSuccess(t *testing.T) {
+	server, _ := newTestServer()
+
+	body := ExecutionRequest{
+		Node: NodeConfig{
+			Name:   "test-node",
+			Config: map[string]interface{}{},
+		},
+		Context: NewMockContext().Build(),
+	}
+	bodyBytes, _ := json.Marshal(body)
+
+	req := httptest.NewRequest(http.MethodPost, "/execute", bytes.NewReader(bodyBytes))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	server.handleExecute(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d", w.Code)
+	}
+
+	var result ExecutionResult
+	if err := json.NewDecoder(w.Body).Decode(&result); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if !result.Success {
+		t.Errorf("expected success, got errors: %v", result.Errors)
+	}
+}
+
+func TestHandleExecuteInvalidJSON(t *testing.T) {
+	server, _ := newTestServer()
+
+	req := httptest.NewRequest(http.MethodPost, "/execute", bytes.NewReader([]byte("not json")))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	server.handleExecute(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400, got %d", w.Code)
+	}
+
+	var result ExecutionResult
+	if err := json.NewDecoder(w.Body).Decode(&result); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if result.Success {
+		t.Error("expected failure for invalid JSON")
+	}
+}
+
+func TestHandleExecuteMethodNotAllowed(t *testing.T) {
+	server, _ := newTestServer()
+
+	req := httptest.NewRequest(http.MethodGet, "/execute", nil)
+	w := httptest.NewRecorder()
+
+	server.handleExecute(w, req)
+
+	if w.Code != http.StatusMethodNotAllowed {
+		t.Errorf("expected 405, got %d", w.Code)
+	}
+}
+
+func TestHandleExecuteNodeNotFound(t *testing.T) {
+	server, _ := newTestServer()
+
+	body := ExecutionRequest{
+		Node: NodeConfig{
+			Name:   "nonexistent",
+			Config: map[string]interface{}{},
+		},
+		Context: NewMockContext().Build(),
+	}
+	bodyBytes, _ := json.Marshal(body)
+
+	req := httptest.NewRequest(http.MethodPost, "/execute", bytes.NewReader(bodyBytes))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	server.handleExecute(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200 (error in body), got %d", w.Code)
+	}
+
+	var result ExecutionResult
+	json.NewDecoder(w.Body).Decode(&result)
+	if result.Success {
+		t.Error("expected failure for nonexistent node")
+	}
+}
+
+func TestHandleHealth(t *testing.T) {
+	server, _ := newTestServer()
+
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	w := httptest.NewRecorder()
+
+	server.handleHealth(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d", w.Code)
+	}
+
+	var health HealthStatus
+	if err := json.NewDecoder(w.Body).Decode(&health); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if health.Status != "healthy" {
+		t.Errorf("expected 'healthy', got %q", health.Status)
+	}
+	if len(health.NodesLoaded) != 1 {
+		t.Errorf("expected 1 node, got %d", len(health.NodesLoaded))
+	}
+}
+
+func TestHandleHealthMethodNotAllowed(t *testing.T) {
+	server, _ := newTestServer()
+
+	req := httptest.NewRequest(http.MethodPost, "/health", nil)
+	w := httptest.NewRecorder()
+
+	server.handleHealth(w, req)
+
+	if w.Code != http.StatusMethodNotAllowed {
+		t.Errorf("expected 405, got %d", w.Code)
+	}
+}
+
+func TestCORSHandler(t *testing.T) {
+	server, _ := newTestServer()
+	server.config.EnableCORS = true
+
+	inner := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+	handler := server.corsHandler(inner)
+
+	// Test OPTIONS preflight
+	req := httptest.NewRequest(http.MethodOptions, "/execute", nil)
+	w := httptest.NewRecorder()
+	handler.ServeHTTP(w, req)
+
+	if w.Code != http.StatusNoContent {
+		t.Errorf("expected 204 for OPTIONS, got %d", w.Code)
+	}
+	if w.Header().Get("Access-Control-Allow-Origin") != "*" {
+		t.Error("expected CORS header")
+	}
+
+	// Test normal request gets CORS headers
+	req = httptest.NewRequest(http.MethodPost, "/execute", nil)
+	w = httptest.NewRecorder()
+	handler.ServeHTTP(w, req)
+
+	if w.Header().Get("Access-Control-Allow-Origin") != "*" {
+		t.Error("expected CORS header on normal request")
+	}
+}

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

@@ -0,0 +1,32 @@
+package blok
+
+import (
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+)
+
+// SetupGracefulShutdown registers signal handlers for SIGINT and SIGTERM
+// and calls the provided cleanup function when a signal is received.
+//
+// Returns a channel that is closed after cleanup completes.
+func SetupGracefulShutdown(cleanup func()) <-chan struct{} {
+	done := make(chan struct{})
+
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+
+	go func() {
+		sig := <-sigCh
+		log.Printf("Received signal: %v", sig)
+
+		if cleanup != nil {
+			cleanup()
+		}
+
+		close(done)
+	}()
+
+	return done
+}

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

@@ -0,0 +1,169 @@
+package blok
+
+import "fmt"
+
+// MockContextBuilder provides a fluent API for building test contexts.
+type MockContextBuilder struct {
+	ctx Context
+}
+
+// NewMockContext starts building a mock context with sensible defaults.
+func NewMockContext() *MockContextBuilder {
+	return &MockContextBuilder{
+		ctx: Context{
+			ID:           "test-execution-id",
+			WorkflowName: "test-workflow",
+			WorkflowPath: "/workflows/test",
+			Request: Request{
+				Body:    map[string]interface{}{},
+				Headers: map[string]string{},
+				Params:  map[string]string{},
+				Query:   map[string]string{},
+				Method:  "POST",
+				URL:     "/test",
+				Cookies: map[string]string{},
+				BaseURL: "http://localhost:8080",
+			},
+			Response: Response{
+				Success: true,
+			},
+			Vars: map[string]interface{}{},
+			Env:  map[string]string{},
+		},
+	}
+}
+
+// WithID sets the execution ID.
+func (b *MockContextBuilder) WithID(id string) *MockContextBuilder {
+	b.ctx.ID = id
+	return b
+}
+
+// WithWorkflow sets the workflow name and path.
+func (b *MockContextBuilder) WithWorkflow(name, path string) *MockContextBuilder {
+	b.ctx.WorkflowName = name
+	b.ctx.WorkflowPath = path
+	return b
+}
+
+// WithBody sets the request body.
+func (b *MockContextBuilder) WithBody(body interface{}) *MockContextBuilder {
+	b.ctx.Request.Body = body
+	return b
+}
+
+// WithHeaders sets the request headers.
+func (b *MockContextBuilder) WithHeaders(headers map[string]string) *MockContextBuilder {
+	b.ctx.Request.Headers = headers
+	return b
+}
+
+// WithParams sets the request params.
+func (b *MockContextBuilder) WithParams(params map[string]string) *MockContextBuilder {
+	b.ctx.Request.Params = params
+	return b
+}
+
+// WithQuery sets the request query parameters.
+func (b *MockContextBuilder) WithQuery(query map[string]string) *MockContextBuilder {
+	b.ctx.Request.Query = query
+	return b
+}
+
+// WithMethod sets the request method.
+func (b *MockContextBuilder) WithMethod(method string) *MockContextBuilder {
+	b.ctx.Request.Method = method
+	return b
+}
+
+// WithURL sets the request URL.
+func (b *MockContextBuilder) WithURL(url string) *MockContextBuilder {
+	b.ctx.Request.URL = url
+	return b
+}
+
+// WithVars sets the context variables.
+func (b *MockContextBuilder) WithVars(vars map[string]interface{}) *MockContextBuilder {
+	b.ctx.Vars = vars
+	return b
+}
+
+// WithVar sets a single context variable.
+func (b *MockContextBuilder) WithVar(key string, value interface{}) *MockContextBuilder {
+	if b.ctx.Vars == nil {
+		b.ctx.Vars = make(map[string]interface{})
+	}
+	b.ctx.Vars[key] = value
+	return b
+}
+
+// WithEnv sets the environment variables.
+func (b *MockContextBuilder) WithEnv(env map[string]string) *MockContextBuilder {
+	b.ctx.Env = env
+	return b
+}
+
+// WithEnvVar sets a single environment variable.
+func (b *MockContextBuilder) WithEnvVar(key, value string) *MockContextBuilder {
+	if b.ctx.Env == nil {
+		b.ctx.Env = make(map[string]string)
+	}
+	b.ctx.Env[key] = value
+	return b
+}
+
+// Build returns the constructed context.
+func (b *MockContextBuilder) Build() Context {
+	return b.ctx
+}
+
+// BuildPtr returns a pointer to the constructed context.
+func (b *MockContextBuilder) BuildPtr() *Context {
+	ctx := b.ctx
+	return &ctx
+}
+
+// TestNodeRunner executes a node in-process for testing.
+type TestNodeRunner struct {
+	registry *NodeRegistry
+}
+
+// NewTestNodeRunner creates a test node runner.
+func NewTestNodeRunner() *TestNodeRunner {
+	return &TestNodeRunner{
+		registry: NewNodeRegistry(),
+	}
+}
+
+// Register registers a node for testing.
+func (r *TestNodeRunner) Register(name string, handler NodeHandler) *TestNodeRunner {
+	r.registry.Register(name, handler)
+	return r
+}
+
+// Execute runs a node by name with the given context and config.
+func (r *TestNodeRunner) Execute(name string, ctx Context, config map[string]interface{}) *ExecutionResult {
+	return r.registry.Execute(&ExecutionRequest{
+		Node: NodeConfig{
+			Name:   name,
+			Config: config,
+		},
+		Context: ctx,
+	})
+}
+
+// AssertSuccess checks that the result is successful and returns the data.
+func AssertSuccess(result *ExecutionResult) (interface{}, error) {
+	if !result.Success {
+		return nil, fmt.Errorf("expected success but got error: %v", result.Errors)
+	}
+	return result.Data, nil
+}
+
+// AssertError checks that the result is an error and returns the error info.
+func AssertError(result *ExecutionResult) (interface{}, error) {
+	if result.Success {
+		return nil, fmt.Errorf("expected error but got success with data: %v", result.Data)
+	}
+	return result.Errors, nil
+}

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

@@ -0,0 +1,124 @@
+package blok
+
+import "testing"
+
+func TestMockContextBuilder(t *testing.T) {
+	ctx := NewMockContext().
+		WithID("custom-id").
+		WithWorkflow("my-workflow", "/workflows/mine").
+		WithBody(map[string]interface{}{"name": "test"}).
+		WithHeaders(map[string]string{"Authorization": "Bearer token"}).
+		WithParams(map[string]string{"id": "123"}).
+		WithQuery(map[string]string{"page": "1"}).
+		WithMethod("GET").
+		WithURL("/api/test").
+		WithVar("key", "value").
+		WithEnvVar("NODE_ENV", "test").
+		Build()
+
+	if ctx.ID != "custom-id" {
+		t.Errorf("expected 'custom-id', got %q", ctx.ID)
+	}
+	if ctx.WorkflowName != "my-workflow" {
+		t.Errorf("expected 'my-workflow', got %q", ctx.WorkflowName)
+	}
+	if ctx.Request.Method != "GET" {
+		t.Errorf("expected 'GET', got %q", ctx.Request.Method)
+	}
+
+	body := ctx.Request.BodyMap()
+	if body["name"] != "test" {
+		t.Errorf("expected body name 'test', got %v", body["name"])
+	}
+
+	if ctx.Vars["key"] != "value" {
+		t.Errorf("expected var 'key' = 'value'")
+	}
+	if ctx.Env["NODE_ENV"] != "test" {
+		t.Errorf("expected env 'NODE_ENV' = 'test'")
+	}
+}
+
+func TestMockContextBuilderDefaults(t *testing.T) {
+	ctx := NewMockContext().Build()
+
+	if ctx.ID == "" {
+		t.Error("expected default ID")
+	}
+	if ctx.WorkflowName == "" {
+		t.Error("expected default workflow name")
+	}
+	if ctx.Request.Method != "POST" {
+		t.Errorf("expected default method 'POST', got %q", ctx.Request.Method)
+	}
+}
+
+func TestMockContextBuildPtr(t *testing.T) {
+	ptr := NewMockContext().BuildPtr()
+	if ptr == nil {
+		t.Fatal("expected non-nil pointer")
+	}
+	if ptr.ID == "" {
+		t.Error("expected non-empty ID")
+	}
+}
+
+func TestTestNodeRunner(t *testing.T) {
+	runner := NewTestNodeRunner()
+	runner.Register("greet", NodeHandlerFunc(func(ctx *Context, config map[string]interface{}) (interface{}, error) {
+		return map[string]string{"message": "hello"}, nil
+	}))
+
+	ctx := NewMockContext().Build()
+	result := runner.Execute("greet", ctx, nil)
+
+	if !result.Success {
+		t.Errorf("expected success, got errors: %v", result.Errors)
+	}
+}
+
+func TestTestNodeRunnerNotFound(t *testing.T) {
+	runner := NewTestNodeRunner()
+	ctx := NewMockContext().Build()
+	result := runner.Execute("missing", ctx, nil)
+
+	if result.Success {
+		t.Error("expected failure for missing node")
+	}
+}
+
+func TestAssertSuccess(t *testing.T) {
+	result := NewSuccessResult("data")
+	data, err := AssertSuccess(result)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if data != "data" {
+		t.Errorf("expected 'data', got %v", data)
+	}
+
+	// Should fail for error result
+	errResult := NewErrorResult("fail")
+	_, err = AssertSuccess(errResult)
+	if err == nil {
+		t.Error("expected error for failed result")
+	}
+}
+
+func TestAssertError(t *testing.T) {
+	result := NewErrorResult("fail")
+	errInfo, err := AssertError(result)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if errInfo == nil {
+		t.Error("expected error info")
+	}
+
+	// Should fail for success result
+	successResult := NewSuccessResult("data")
+	_, err = AssertError(successResult)
+	if err == nil {
+		t.Error("expected error for success result")
+	}
+}