blokctl 1.2.0 → 1.4.0

package/dist/scaffold-repo/sdks/java/README.md

@@ -0,0 +1,221 @@
+# Blok Blok Java SDK
+
+Java SDK for 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.
+
+## Installation
+
+### Maven
+
+```xml
+<dependency>
+    <groupId>com.blok</groupId>
+    <artifactId>blok-java</artifactId>
+    <version>1.0.0</version>
+</dependency>
+```
+
+### Build from source
+
+```bash
+mvn clean package
+```
+
+## Quick Start
+
+### 1. Implement a node
+
+```java
+import com.blok.blok.node.NodeHandler;
+import com.blok.blok.types.Context;
+import java.util.Map;
+
+public class GreetNode implements NodeHandler {
+    @Override
+    public Object execute(Context ctx, Map<String, Object> config) throws Exception {
+        String name = "World";
+        Map<String, Object> body = ctx.getRequest().bodyMap();
+        if (body != null && body.get("name") instanceof String s) {
+            name = s;
+        }
+        return Map.of("message", "Hello, " + name + "!");
+    }
+}
+```
+
+### 2. Register and serve
+
+```java
+import com.blok.blok.config.ServerConfig;
+import com.blok.blok.node.NodeRegistry;
+import com.blok.blok.server.RuntimeServer;
+
+public class Main {
+    public static void main(String[] args) throws Exception {
+        NodeRegistry registry = new NodeRegistry();
+        registry.register("greet", new GreetNode());
+
+        ServerConfig config = ServerConfig.fromEnv();
+        RuntimeServer server = new RuntimeServer(registry, config);
+        server.start();
+    }
+}
+```
+
+### 3. Test the endpoint
+
+```bash
+curl -X POST http://localhost:8080/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "node": {"name": "greet", "config": {}},
+    "context": {
+      "id": "1",
+      "request": {"body": {"name": "Blok"}, "method": "POST", "url": "/", "headers": {}, "params": {}, "query": {}, "cookies": {}, "baseUrl": ""},
+      "response": {},
+      "vars": {},
+      "env": {}
+    }
+  }'
+```
+
+## Configuration
+
+Configuration is loaded from environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `8080` | HTTP port |
+| `HOST` | `0.0.0.0` | Bind address |
+| `VERSION` | `1.0.0` | Runtime version (reported in health) |
+| `LOG_LEVEL` | `INFO` | Minimum log level: DEBUG, INFO, WARN, ERROR |
+| `ENABLE_CORS` | `false` | Enable CORS headers |
+| `SHUTDOWN_TIMEOUT` | `10` | Graceful shutdown timeout (seconds) |
+
+## Middleware
+
+Middleware wraps node execution to add cross-cutting behavior.
+
+```java
+import com.blok.blok.middleware.*;
+import com.blok.blok.logging.Logger;
+import com.blok.blok.logging.LogLevel;
+
+Logger logger = new Logger(LogLevel.INFO);
+
+registry.use(new RecoveryMiddleware());
+registry.use(new LoggingMiddleware(logger));
+```
+
+Built-in middleware:
+- **RecoveryMiddleware** -- catches exceptions, converts to structured error results
+- **LoggingMiddleware** -- logs execution start/end with timing
+
+Custom middleware:
+
+```java
+Middleware timing = next -> (ctx, config) -> {
+    long start = System.nanoTime();
+    Object result = next.execute(ctx, config);
+    System.out.println("Took " + (System.nanoTime() - start) / 1_000_000 + "ms");
+    return result;
+};
+registry.use(timing);
+```
+
+## Validation
+
+Lightweight JSON Schema validation (subset of Draft 7):
+
+```java
+import com.blok.blok.validation.SchemaValidator;
+import java.util.*;
+
+SchemaValidator validator = new SchemaValidator();
+Map<String, Object> schema = Map.of(
+    "type", "object",
+    "required", List.of("name", "email"),
+    "properties", Map.of(
+        "name", Map.of("type", "string", "minLength", 1),
+        "email", Map.of("type", "string")
+    )
+);
+
+List<String> errors = validator.validate(data, schema);
+```
+
+Supported keywords: `type`, `required`, `properties`, `enum`, `minLength`, `maxLength`, `minimum`, `maximum`.
+
+## Testing
+
+Use the built-in test utilities:
+
+```java
+import com.blok.blok.testing.MockContext;
+import com.blok.blok.testing.TestRunner;
+
+TestRunner runner = new TestRunner();
+runner.register("greet", new GreetNode());
+
+Context ctx = new MockContext()
+    .withBody(Map.of("name", "Test"))
+    .build();
+
+ExecutionResult result = runner.execute("greet", ctx, Map.of());
+assert result.isSuccess();
+```
+
+Run the test suite:
+
+```bash
+mvn test
+```
+
+## Error Handling
+
+Structured errors with categories:
+
+```java
+import com.blok.blok.errors.NodeException;
+
+throw NodeException.validation("name is required");
+throw NodeException.configuration("missing 'url' in config");
+throw NodeException.network("connection refused", cause);
+throw NodeException.notFound("resource not found");
+throw NodeException.execution("processing failed");
+```
+
+Error categories: `VALIDATION`, `EXECUTION`, `CONFIGURATION`, `NETWORK`, `NOT_FOUND`.
+
+## Docker
+
+```bash
+# Build
+docker build -t blok-blok-java .
+
+# Run
+docker run -p 8080:8080 blok-blok-java
+
+# Health check
+curl http://localhost:8080/health
+```
+
+## Project Structure
+
+```
+src/main/java/com/blok/blok/
+  types/          Context, Request, Response, NodeConfig, ExecutionRequest/Result
+  node/           NodeHandler interface, NodeRegistry
+  server/         RuntimeServer (JDK HttpServer)
+  middleware/     Middleware, MiddlewareChain, Logging, Recovery
+  validation/     SchemaValidator
+  logging/        Logger, LogLevel, LogEntry
+  errors/         NodeException, ErrorCategory
+  config/         ServerConfig
+  testing/        MockContext, TestRunner
+  nodes/          HelloWorldNode, ApiCallNode, TransformDataNode
+  Main.java       Entry point
+```
+
+## License
+
+See repository root for license information.

package/dist/scaffold-repo/sdks/java/pom.xml

@@ -0,0 +1,163 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.blok</groupId>
+    <artifactId>blok-java</artifactId>
+    <version>1.0.0</version>
+    <packaging>jar</packaging>
+
+    <name>Blok Blok Java SDK</name>
+    <description>Java SDK for building Blok blok workflow nodes (HTTP and gRPC transports).</description>
+    <url>https://github.com/nickincloud/blok-java</url>
+
+    <properties>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <gson.version>2.10.1</gson.version>
+        <junit.version>5.10.1</junit.version>
+        <grpc.version>1.69.0</grpc.version>
+        <protobuf.version>3.25.5</protobuf.version>
+        <main.class>com.blok.blok.Main</main.class>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.google.code.gson</groupId>
+            <artifactId>gson</artifactId>
+            <version>${gson.version}</version>
+        </dependency>
+
+        <!-- gRPC stack: server + protobuf runtime + stub. `grpc-netty-shaded`
+             bundles Netty so we don't need to manage its transitive Netty
+             alignment ourselves. -->
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-netty-shaded</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-protobuf</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-stub</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.protobuf</groupId>
+            <artifactId>protobuf-java</artifactId>
+            <version>${protobuf.version}</version>
+        </dependency>
+        <!-- Generated gRPC stubs reference `javax.annotation.Generated` which
+             was removed from the JDK in Java 11+. Provide the legacy artifact
+             so the generated code compiles on Java 17+. -->
+        <dependency>
+            <groupId>javax.annotation</groupId>
+            <artifactId>javax.annotation-api</artifactId>
+            <version>1.3.2</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>${junit.version}</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <!-- `os-maven-plugin` injects `os.detected.classifier` so
+             `protobuf-maven-plugin` can pick the right protoc binary for the
+             host platform without users installing protoc separately. -->
+        <extensions>
+            <extension>
+                <groupId>kr.motd.maven</groupId>
+                <artifactId>os-maven-plugin</artifactId>
+                <version>1.7.1</version>
+            </extension>
+        </extensions>
+
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.11.0</version>
+                <configuration>
+                    <source>17</source>
+                    <target>17</target>
+                </configuration>
+            </plugin>
+
+            <!-- Compile `runtime.proto` to Java + gRPC stubs at build time.
+                 Uses vendored protoc binaries — no host install required. -->
+            <plugin>
+                <groupId>org.xolstice.maven.plugins</groupId>
+                <artifactId>protobuf-maven-plugin</artifactId>
+                <version>0.6.1</version>
+                <configuration>
+                    <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
+                    <pluginId>grpc-java</pluginId>
+                    <pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
+                    <protoSourceRoot>${project.basedir}/src/main/proto</protoSourceRoot>
+                </configuration>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>compile</goal>
+                            <goal>compile-custom</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>3.2.2</version>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>3.5.1</version>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                        <configuration>
+                            <transformers>
+                                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                                    <mainClass>${main.class}</mainClass>
+                                </transformer>
+                                <!-- grpc-netty-shaded uses META-INF/services SPI; the ServicesResourceTransformer concatenates them. -->
+                                <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
+                            </transformers>
+                            <createDependencyReducedPom>false</createDependencyReducedPom>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+                <version>3.3.0</version>
+                <configuration>
+                    <archive>
+                        <manifest>
+                            <mainClass>${main.class}</mainClass>
+                        </manifest>
+                    </archive>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>

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

@@ -0,0 +1,90 @@
+package com.blok.blok;
+
+import com.blok.blok.config.ServerConfig;
+import com.blok.blok.logging.Logger;
+import com.blok.blok.middleware.LoggingMiddleware;
+import com.blok.blok.middleware.RecoveryMiddleware;
+import com.blok.blok.node.NodeRegistry;
+import com.blok.blok.nodes.ApiCallNode;
+import com.blok.blok.nodes.BlokErrorDemoNode;
+import com.blok.blok.nodes.ChainTestNode;
+import com.blok.blok.nodes.HelloWorldNode;
+import com.blok.blok.nodes.TransformDataNode;
+import com.blok.blok.server.BlokGrpcServer;
+import com.blok.blok.server.RuntimeServer;
+
+/**
+ * Entry point for the Blok blok Java runtime.
+ * <p>
+ * Registers all built-in example nodes, configures middleware, and starts
+ * the configured server(s). The {@code BLOK_TRANSPORT} environment variable
+ * selects between HTTP-only ({@code "http"}, default), gRPC-only
+ * ({@code "grpc"}), or both transports concurrently ({@code "both"}).
+ */
+public class Main {
+
+    public static void main(String[] args) {
+        ServerConfig config = ServerConfig.fromEnv();
+
+        NodeRegistry registry = new NodeRegistry();
+        registry.register("hello-world", new HelloWorldNode());
+        registry.register("api-call", new ApiCallNode());
+        registry.register("transform-data", new TransformDataNode());
+        registry.register("chain-test", new ChainTestNode());
+        registry.register("blok-error-demo", new BlokErrorDemoNode());
+        registry.register("typed-greet", new com.blok.blok.nodes.TypedGreetNode());
+
+        // Register user nodes scaffolded under runtimes/java/nodes. No-op in the
+        // SDK tree; blokctl regenerates UserNodeRegistry.java per project.
+        UserNodeRegistry.registerUserNodes(registry);
+
+        Logger logger = new Logger(config.getLogLevel());
+        registry.use(new RecoveryMiddleware());
+        registry.use(new LoggingMiddleware(logger));
+
+        try {
+            switch (config.getTransport()) {
+                case HTTP -> runHttp(registry, config);
+                case GRPC -> runGrpc(registry, config);
+                case BOTH -> runBoth(registry, config);
+            }
+        } catch (Exception e) {
+            System.err.println("Failed to start server: " + e.getMessage());
+            System.exit(1);
+        }
+    }
+
+    private static void runHttp(NodeRegistry registry, ServerConfig config) throws Exception {
+        RuntimeServer server = new RuntimeServer(registry, config);
+        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+            server.stop();
+            System.out.println("Blok HTTP server stopped.");
+        }));
+        server.start();
+    }
+
+    private static void runGrpc(NodeRegistry registry, ServerConfig config) throws Exception {
+        BlokGrpcServer grpc = new BlokGrpcServer(registry, config.getGrpcPort(), config.getVersion());
+        grpc.start();
+        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+            grpc.stop();
+            System.out.println("Blok gRPC server stopped.");
+        }));
+        grpc.blockUntilShutdown();
+    }
+
+    private static void runBoth(NodeRegistry registry, ServerConfig config) throws Exception {
+        BlokGrpcServer grpc = new BlokGrpcServer(registry, config.getGrpcPort(), config.getVersion());
+        grpc.start();
+
+        RuntimeServer http = new RuntimeServer(registry, config);
+
+        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+            grpc.stop();
+            http.stop();
+            System.out.println("Blok runtime servers stopped.");
+        }));
+
+        http.start();
+    }
+}

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

@@ -0,0 +1,19 @@
+// Code generated by blokctl. DO NOT EDIT.
+//
+// Default no-op shim. `blokctl dev` regenerates this in
+// .blok/runtimes/java/src/main/java/com/blok/blok with the user nodes
+// scaffolded under runtimes/java/nodes. Committed so the SDK compiles without
+// codegen — e.g. the cross-runtime CI build, which has no user nodes.
+package com.blok.blok;
+
+import com.blok.blok.node.NodeRegistry;
+
+public final class UserNodeRegistry {
+
+    private UserNodeRegistry() {
+    }
+
+    /** Registers nodes scaffolded under runtimes/java/nodes. */
+    public static void registerUserNodes(NodeRegistry registry) {
+    }
+}