blokctl 1.3.0 → 1.4.0

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/testing/MockContext.java

@@ -0,0 +1,120 @@
+package com.blok.blok.testing;
+
+import com.blok.blok.types.Context;
+import com.blok.blok.types.Request;
+import com.blok.blok.types.Response;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Fluent builder for creating test {@link Context} instances with sensible defaults.
+ * <p>
+ * Example:
+ * <pre>{@code
+ * Context ctx = new MockContext()
+ *     .withId("test-123")
+ *     .withWorkflow("my-workflow", "/workflows/test")
+ *     .withBody(Map.of("name", "World"))
+ *     .withVar("key", "value")
+ *     .build();
+ * }</pre>
+ */
+public class MockContext {
+
+    private String id = "test-execution-id";
+    private String workflowName = "test-workflow";
+    private String workflowPath = "/workflows/test";
+    private Object body = new HashMap<String, Object>();
+    private Map<String, String> headers = new HashMap<>();
+    private Map<String, String> params = new HashMap<>();
+    private Map<String, String> query = new HashMap<>();
+    private String method = "POST";
+    private String url = "/test";
+    private Map<String, String> cookies = new HashMap<>();
+    private String baseUrl = "http://localhost:8080";
+    private Map<String, Object> vars = new HashMap<>();
+    private Map<String, String> env = new HashMap<>();
+
+    public MockContext() {
+    }
+
+    /**
+     * Sets the execution ID.
+     */
+    public MockContext withId(String id) {
+        this.id = id;
+        return this;
+    }
+
+    /**
+     * Sets the workflow name and path.
+     */
+    public MockContext withWorkflow(String name, String path) {
+        this.workflowName = name;
+        this.workflowPath = path;
+        return this;
+    }
+
+    /**
+     * Sets the request body.
+     */
+    public MockContext withBody(Object body) {
+        this.body = body;
+        return this;
+    }
+
+    /**
+     * Sets the request headers.
+     */
+    public MockContext withHeaders(Map<String, String> headers) {
+        this.headers = headers != null ? new HashMap<>(headers) : new HashMap<>();
+        return this;
+    }
+
+    /**
+     * Sets a single context variable.
+     */
+    public MockContext withVar(String key, Object value) {
+        this.vars.put(key, value);
+        return this;
+    }
+
+    /**
+     * Sets a single environment variable.
+     */
+    public MockContext withEnv(String key, String value) {
+        this.env.put(key, value);
+        return this;
+    }
+
+    /**
+     * Builds and returns the Context.
+     */
+    public Context build() {
+        Context ctx = new Context();
+        ctx.setId(id);
+        ctx.setWorkflowName(workflowName);
+        ctx.setWorkflowPath(workflowPath);
+
+        Request request = new Request();
+        request.setBody(body);
+        request.setHeaders(new HashMap<>(headers));
+        request.setParams(new HashMap<>(params));
+        request.setQuery(new HashMap<>(query));
+        request.setMethod(method);
+        request.setUrl(url);
+        request.setCookies(new HashMap<>(cookies));
+        request.setBaseUrl(baseUrl);
+        ctx.setRequest(request);
+
+        Response response = new Response();
+        response.setSuccess(true);
+        ctx.setResponse(response);
+
+        ctx.setVars(new HashMap<>(vars));
+        ctx.setEnv(new HashMap<>(env));
+
+        return ctx;
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/testing/TestRunner.java

@@ -0,0 +1,59 @@
+package com.blok.blok.testing;
+
+import com.blok.blok.node.NodeHandler;
+import com.blok.blok.node.NodeRegistry;
+import com.blok.blok.types.*;
+
+import java.util.Map;
+
+/**
+ * Test runner for executing nodes in-process without starting an HTTP server.
+ * <p>
+ * Example:
+ * <pre>{@code
+ * TestRunner runner = new TestRunner();
+ * runner.register("hello", new HelloWorldNode());
+ *
+ * Context ctx = new MockContext().withBody(Map.of("name", "World")).build();
+ * ExecutionResult result = runner.execute("hello", ctx, Map.of("prefix", "Hi"));
+ *
+ * assert result.isSuccess();
+ * }</pre>
+ */
+public class TestRunner {
+
+    private final NodeRegistry registry;
+
+    public TestRunner() {
+        this.registry = new NodeRegistry();
+    }
+
+    /**
+     * Registers a node handler for testing.
+     *
+     * @param name    the node name
+     * @param handler the node handler
+     * @return this runner for fluent use
+     */
+    public TestRunner register(String name, NodeHandler handler) {
+        registry.register(name, handler);
+        return this;
+    }
+
+    /**
+     * Executes a node by name with the given context and config.
+     *
+     * @param name   the node name
+     * @param ctx    the execution context
+     * @param config the node config map
+     * @return the execution result
+     */
+    public ExecutionResult execute(String name, Context ctx, Map<String, Object> config) {
+        NodeConfig nodeConfig = new NodeConfig();
+        nodeConfig.setName(name);
+        nodeConfig.setConfig(config);
+
+        ExecutionRequest request = new ExecutionRequest(nodeConfig, ctx);
+        return registry.execute(request);
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/types/Context.java

@@ -0,0 +1,167 @@
+package com.blok.blok.types;
+
+import com.google.gson.annotations.SerializedName;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Represents the workflow execution context passed between nodes.
+ * Contains request data, response state, variables, and environment configuration.
+ */
+public class Context {
+
+    private String id;
+
+    @SerializedName("workflow_name")
+    private String workflowName;
+
+    @SerializedName("workflow_path")
+    private String workflowPath;
+
+    private Request request;
+    private Response response;
+    private Map<String, Object> vars;
+    private Map<String, String> env;
+
+    public Context() {
+        this.request = new Request();
+        this.response = new Response();
+        this.vars = new HashMap<>();
+        this.env = new HashMap<>();
+    }
+
+    /**
+     * Stores a variable in the context for downstream nodes.
+     *
+     * @param key   the variable name
+     * @param value the variable value
+     */
+    public void setVar(String key, Object value) {
+        if (key == null) {
+            throw new IllegalArgumentException("key must not be null");
+        }
+        if (vars == null) {
+            vars = new HashMap<>();
+        }
+        vars.put(key, value);
+    }
+
+    /**
+     * Retrieves a variable from the context.
+     *
+     * @param key the variable name
+     * @return the value, or null if not present
+     */
+    public Object getVar(String key) {
+        if (key == null || vars == null) {
+            return null;
+        }
+        return vars.get(key);
+    }
+
+    /**
+     * Retrieves a string variable from the context.
+     *
+     * @param key the variable name
+     * @return the string value, or empty string if not present or not a string
+     */
+    public String getVarString(String key) {
+        Object value = getVar(key);
+        if (value instanceof String) {
+            return (String) value;
+        }
+        return "";
+    }
+
+    // Getters and setters
+
+    public String getId() {
+        return id;
+    }
+
+    public void setId(String id) {
+        this.id = id;
+    }
+
+    public String getWorkflowName() {
+        return workflowName;
+    }
+
+    public void setWorkflowName(String workflowName) {
+        this.workflowName = workflowName;
+    }
+
+    public String getWorkflowPath() {
+        return workflowPath;
+    }
+
+    public void setWorkflowPath(String workflowPath) {
+        this.workflowPath = workflowPath;
+    }
+
+    public Request getRequest() {
+        return request;
+    }
+
+    public void setRequest(Request request) {
+        this.request = request != null ? request : new Request();
+    }
+
+    public Response getResponse() {
+        return response;
+    }
+
+    public void setResponse(Response response) {
+        this.response = response != null ? response : new Response();
+    }
+
+    public Map<String, Object> getVars() {
+        return vars;
+    }
+
+    public void setVars(Map<String, Object> vars) {
+        this.vars = vars != null ? vars : new HashMap<>();
+    }
+
+    public Map<String, String> getEnv() {
+        return env;
+    }
+
+    public void setEnv(Map<String, String> env) {
+        this.env = env != null ? env : new HashMap<>();
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        Context context = (Context) o;
+        return Objects.equals(id, context.id) &&
+                Objects.equals(workflowName, context.workflowName) &&
+                Objects.equals(workflowPath, context.workflowPath) &&
+                Objects.equals(request, context.request) &&
+                Objects.equals(response, context.response) &&
+                Objects.equals(vars, context.vars) &&
+                Objects.equals(env, context.env);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(id, workflowName, workflowPath, request, response, vars, env);
+    }
+
+    @Override
+    public String toString() {
+        return "Context{" +
+                "id='" + id + '\'' +
+                ", workflowName='" + workflowName + '\'' +
+                ", workflowPath='" + workflowPath + '\'' +
+                ", request=" + request +
+                ", response=" + response +
+                ", vars=" + vars +
+                ", env=" + env +
+                '}';
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/types/ExecutionMetrics.java

@@ -0,0 +1,80 @@
+package com.blok.blok.types;
+
+import com.google.gson.annotations.SerializedName;
+
+import java.util.Objects;
+
+/**
+ * Captures performance metrics for a node execution.
+ * Null fields are omitted during JSON serialization.
+ */
+public class ExecutionMetrics {
+
+    @SerializedName("duration_ms")
+    private Double durationMs;
+
+    @SerializedName("cpu_ms")
+    private Double cpuMs;
+
+    @SerializedName("memory_bytes")
+    private Long memoryBytes;
+
+    public ExecutionMetrics() {
+    }
+
+    public ExecutionMetrics(Double durationMs, Double cpuMs, Long memoryBytes) {
+        this.durationMs = durationMs;
+        this.cpuMs = cpuMs;
+        this.memoryBytes = memoryBytes;
+    }
+
+    // Getters and setters
+
+    public Double getDurationMs() {
+        return durationMs;
+    }
+
+    public void setDurationMs(Double durationMs) {
+        this.durationMs = durationMs;
+    }
+
+    public Double getCpuMs() {
+        return cpuMs;
+    }
+
+    public void setCpuMs(Double cpuMs) {
+        this.cpuMs = cpuMs;
+    }
+
+    public Long getMemoryBytes() {
+        return memoryBytes;
+    }
+
+    public void setMemoryBytes(Long memoryBytes) {
+        this.memoryBytes = memoryBytes;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        ExecutionMetrics that = (ExecutionMetrics) o;
+        return Objects.equals(durationMs, that.durationMs) &&
+                Objects.equals(cpuMs, that.cpuMs) &&
+                Objects.equals(memoryBytes, that.memoryBytes);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(durationMs, cpuMs, memoryBytes);
+    }
+
+    @Override
+    public String toString() {
+        return "ExecutionMetrics{" +
+                "durationMs=" + durationMs +
+                ", cpuMs=" + cpuMs +
+                ", memoryBytes=" + memoryBytes +
+                '}';
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/types/ExecutionRequest.java

@@ -0,0 +1,61 @@
+package com.blok.blok.types;
+
+import java.util.Objects;
+
+/**
+ * Represents the execution request received from the Blok runner.
+ * Contains the node configuration and the workflow execution context.
+ */
+public class ExecutionRequest {
+
+    private NodeConfig node;
+    private Context context;
+
+    public ExecutionRequest() {
+    }
+
+    public ExecutionRequest(NodeConfig node, Context context) {
+        this.node = node;
+        this.context = context;
+    }
+
+    // Getters and setters
+
+    public NodeConfig getNode() {
+        return node;
+    }
+
+    public void setNode(NodeConfig node) {
+        this.node = node;
+    }
+
+    public Context getContext() {
+        return context;
+    }
+
+    public void setContext(Context context) {
+        this.context = context;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        ExecutionRequest that = (ExecutionRequest) o;
+        return Objects.equals(node, that.node) &&
+                Objects.equals(context, that.context);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(node, context);
+    }
+
+    @Override
+    public String toString() {
+        return "ExecutionRequest{" +
+                "node=" + node +
+                ", context=" + context +
+                '}';
+    }
+}

package/dist/scaffold-repo/sdks/java/src/main/java/com/blok/blok/types/ExecutionResult.java

@@ -0,0 +1,188 @@
+package com.blok.blok.types;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Represents the execution result returned to the Blok runner.
+ * <p>
+ * The {@code logs} and {@code metrics} fields are omitted from JSON when null
+ * (handled by Gson's null exclusion strategy configured in the server).
+ */
+public class ExecutionResult {
+
+    private boolean success;
+    private Object data;
+    private Object errors;
+    private List<String> logs;
+    private ExecutionMetrics metrics;
+    private Map<String, Object> vars;
+
+    public ExecutionResult() {
+    }
+
+    private ExecutionResult(boolean success, Object data, Object errors) {
+        this.success = success;
+        this.data = data;
+        this.errors = errors;
+    }
+
+    /**
+     * Creates a successful execution result with the given data.
+     *
+     * @param data the result data
+     * @return a success result
+     */
+    public static ExecutionResult success(Object data) {
+        return new ExecutionResult(true, data, null);
+    }
+
+    /**
+     * Creates a failed execution result with an error message.
+     *
+     * @param message the error message
+     * @return an error result
+     */
+    public static ExecutionResult error(String message) {
+        if (message == null) {
+            message = "unknown error";
+        }
+        Map<String, String> errorMap = new HashMap<>();
+        errorMap.put("message", message);
+        return new ExecutionResult(false, null, errorMap);
+    }
+
+    /**
+     * Creates a failed execution result with an error message and additional details.
+     *
+     * @param message the error message
+     * @param details additional error details
+     * @return an error result with details
+     */
+    public static ExecutionResult errorWithDetails(String message, Map<String, Object> details) {
+        if (message == null) {
+            message = "unknown error";
+        }
+        Map<String, Object> errorMap = new HashMap<>();
+        errorMap.put("message", message);
+        if (details != null) {
+            errorMap.put("details", details);
+        }
+        return new ExecutionResult(false, null, errorMap);
+    }
+
+    /**
+     * Fluent setter to attach log lines to this result.
+     *
+     * @param logs the log lines
+     * @return this result
+     */
+    public ExecutionResult withLogs(List<String> logs) {
+        this.logs = logs;
+        return this;
+    }
+
+    /**
+     * Fluent setter to attach execution metrics to this result.
+     *
+     * @param metrics the execution metrics
+     * @return this result
+     */
+    public ExecutionResult withMetrics(ExecutionMetrics metrics) {
+        this.metrics = metrics;
+        return this;
+    }
+
+    // Getters and setters
+
+    public boolean isSuccess() {
+        return success;
+    }
+
+    public void setSuccess(boolean success) {
+        this.success = success;
+    }
+
+    public Object getData() {
+        return data;
+    }
+
+    public void setData(Object data) {
+        this.data = data;
+    }
+
+    public Object getErrors() {
+        return errors;
+    }
+
+    public void setErrors(Object errors) {
+        this.errors = errors;
+    }
+
+    public List<String> getLogs() {
+        return logs;
+    }
+
+    public void setLogs(List<String> logs) {
+        this.logs = logs;
+    }
+
+    public ExecutionMetrics getMetrics() {
+        return metrics;
+    }
+
+    public void setMetrics(ExecutionMetrics metrics) {
+        this.metrics = metrics;
+    }
+
+    public Map<String, Object> getVars() {
+        return vars;
+    }
+
+    public void setVars(Map<String, Object> vars) {
+        this.vars = vars;
+    }
+
+    /**
+     * Fluent setter to attach context variables to this result.
+     *
+     * @param vars the context variables
+     * @return this result
+     */
+    public ExecutionResult withVars(Map<String, Object> vars) {
+        this.vars = vars;
+        return this;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        ExecutionResult that = (ExecutionResult) o;
+        return success == that.success &&
+                Objects.equals(data, that.data) &&
+                Objects.equals(errors, that.errors) &&
+                Objects.equals(logs, that.logs) &&
+                Objects.equals(metrics, that.metrics) &&
+                Objects.equals(vars, that.vars);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(success, data, errors, logs, metrics, vars);
+    }
+
+    @Override
+    public String toString() {
+        return "ExecutionResult{" +
+                "success=" + success +
+                ", data=" + data +
+                ", errors=" + errors +
+                ", logs=" + logs +
+                ", metrics=" + metrics +
+                ", vars=" + vars +
+                '}';
+    }
+}