blokctl 1.3.0 → 1.4.0

package/dist/scaffold-repo/sdks/rust/Cargo.toml

@@ -0,0 +1,82 @@
+[package]
+name = "blok-rs"
+version = "1.0.0"
+edition = "2021"
+description = "Blok Runtime SDK for Rust — Build workflow nodes in Rust for the Blok orchestration framework"
+license = "MIT"
+repository = "https://github.com/nickincloud/blok-rs"
+keywords = ["blok", "workflow", "runtime", "orchestration", "grpc"]
+categories = ["web-programming", "network-programming"]
+readme = "README.md"
+
+[[bin]]
+name = "blok"
+path = "src/main.rs"
+
+[lib]
+name = "blok"
+path = "src/lib.rs"
+
+[features]
+default = ["http"]
+http = ["axum", "tower", "tower-http"]
+# `tonic-build` is a build-time dep needed to compile `proto/blok/runtime/v1/runtime.proto`
+# at compile time. Listed here so `--features grpc` activates the runtime
+# stack (tonic/prost/base64) AND the build script in one step.
+grpc = ["tonic", "prost", "prost-types", "base64", "tokio-stream", "dep:tonic-build", "dep:protoc-bin-vendored"]
+worker = ["async-nats", "tokio-stream"]
+full = ["http", "grpc", "worker"]
+
+[dependencies]
+# Async runtime
+tokio = { version = "1", features = ["full"] }
+
+# HTTP server (feature-gated)
+axum = { version = "0.7", features = ["json"], optional = true }
+tower = { version = "0.4", features = ["timeout"], optional = true }
+tower-http = { version = "0.5", features = ["cors", "trace"], optional = true }
+
+# gRPC server (feature-gated)
+tonic = { version = "0.12", optional = true }
+prost = { version = "0.13", optional = true }
+# Provides `prost_types::Timestamp` and other well-known types referenced by
+# `runtime.proto` (`google.protobuf.Timestamp`).
+prost-types = { version = "0.13", optional = true }
+base64 = { version = "0.22", optional = true }
+
+# Serialization
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+# JSON Schema derive for the typed `TypedNode` contract (SPEC-B P3) — powers
+# input/output validation reflection surfaced via gRPC ListNodes.
+schemars = "0.8"
+
+# Logging
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+
+# Utilities
+async-trait = "0.1"
+thiserror = "1"
+chrono = { version = "0.4", features = ["serde"] }
+
+# NATS JetStream worker (feature-gated)
+async-nats = { version = "0.38", optional = true }
+tokio-stream = { version = "0.1", optional = true }
+
+# HTTP client for example nodes
+reqwest = { version = "0.12", features = ["json"] }
+
+[dev-dependencies]
+axum-test = "14"
+tokio-test = "0.4"
+reqwest = { version = "0.12", features = ["json"] }
+
+[build-dependencies]
+tonic-build = { version = "0.12", optional = true }
+# Bundle a `protoc` binary so the Rust SDK builds without requiring users to
+# install Google Protocol Buffers separately. Activated with the `grpc` feature.
+protoc-bin-vendored = { version = "3", optional = true }
+
+[package.metadata.docs.rs]
+all-features = true

package/dist/scaffold-repo/sdks/rust/Dockerfile

@@ -0,0 +1,40 @@
+# Build stage
+FROM rust:1.84-alpine AS builder
+
+RUN apk add --no-cache musl-dev pkgconfig openssl-dev openssl-libs-static
+
+WORKDIR /app
+
+COPY Cargo.toml Cargo.lock* ./
+
+# Create dummy source for dependency caching
+RUN mkdir -p src && \
+    echo 'fn main() {}' > src/main.rs && \
+    echo '' > src/lib.rs && \
+    cargo build --release 2>/dev/null || true && \
+    rm -rf src
+
+COPY . .
+# The gRPC server lives behind the `grpc` cargo feature — the runner only speaks
+# gRPC, so it must be compiled in (default features are http-only).
+RUN cargo build --release --features grpc
+
+# Runtime stage
+FROM alpine:3.19
+RUN apk --no-cache add ca-certificates
+WORKDIR /app
+COPY --from=builder /app/target/release/blok .
+
+# HTTP port (informational /health) + gRPC port (the runner only speaks gRPC).
+EXPOSE 8080 10002
+
+ENV PORT=8080
+ENV GRPC_PORT=10002
+ENV ENABLE_GRPC=true
+ENV VERSION=1.0.0
+ENV RUST_LOG=info
+
+HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget -qO- http://127.0.0.1:8080/health || exit 1
+
+ENTRYPOINT ["./blok"]

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

@@ -0,0 +1,73 @@
+# blok-rs
+
+Rust SDK for the Blok blok workflow orchestration framework.
+
+Build high-performance workflow nodes in Rust with async/await support.
+
+## Installation
+
+```toml
+[dependencies]
+blok-rs = "1.0"
+```
+
+## Quick Start
+
+```rust
+use async_trait::async_trait;
+use blok::{NodeHandler, NodeRegistry, Context};
+use std::collections::HashMap;
+
+struct GreetNode;
+
+#[async_trait]
+impl NodeHandler for GreetNode {
+    async fn execute(
+        &self,
+        ctx: &mut Context,
+        config: &HashMap<String, serde_json::Value>,
+    ) -> Result<serde_json::Value, Box<dyn std::error::Error + Send + Sync>> {
+        let name = ctx.request.body_str("name").unwrap_or("World");
+        Ok(serde_json::json!({ "message": format!("Hello, {}!", name) }))
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    let mut registry = NodeRegistry::new("1.0.0");
+    registry.register("greet", GreetNode);
+    blok::server::serve(registry, 8080).await.unwrap();
+}
+```
+
+## Features
+
+- **Async/await** - Built on tokio for maximum performance
+- **HTTP + gRPC** - Serve via axum (HTTP) or tonic (gRPC, feature-gated)
+- **Middleware** - Composable middleware pipeline (logging, timeout)
+- **Validation** - JSON Schema validation for inputs/outputs
+- **Structured logging** - Log capture for ExecutionResult.logs
+- **Testing utilities** - MockContext builder and TestNodeRunner
+- **Type-safe errors** - NodeError with categories via thiserror
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `8080` | HTTP port |
+| `HOST` | `0.0.0.0` | Bind address |
+| `VERSION` | `1.0.0` | Runtime version |
+| `RUST_LOG` | `info` | tracing log level |
+| `ENABLE_CORS` | `false` | Enable CORS |
+| `ENABLE_GRPC` | `false` | Enable gRPC server |
+| `GRPC_PORT` | `50051` | gRPC port |
+
+## Cargo Features
+
+- `http` (default) — HTTP server via axum
+- `grpc` — gRPC server via tonic
+- `full` — Both HTTP and gRPC
+
+## License
+
+MIT

package/dist/scaffold-repo/sdks/rust/build.rs

@@ -0,0 +1,32 @@
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    #[cfg(feature = "grpc")]
+    {
+        // Use a vendored `protoc` binary so the SDK builds on machines that
+        // do not have Google Protocol Buffers installed. The crate ships
+        // protoc binaries for every Tier-1 platform.
+        let protoc = protoc_bin_vendored::protoc_bin_path()
+            .expect("vendored protoc binary should be available");
+        std::env::set_var("PROTOC", protoc);
+
+        // Compile the canonical Blok runtime v1 proto.
+        // Source of truth lives at repo-root `proto/blok/runtime/v1/runtime.proto`
+        // and is mirrored into this crate at `proto/blok/runtime/v1/runtime.proto`
+        // via `make proto-rust` from the repo root.
+        // Generate both server and client. The client stubs are needed by
+        // integration tests in `tests/` and may be useful for SDK consumers
+        // that want to call `NodeRuntime` from Rust (e.g. composing nodes
+        // that delegate to other runtimes).
+        tonic_build::configure()
+            .build_server(true)
+            .build_client(true)
+            .compile_protos(
+                &["proto/blok/runtime/v1/runtime.proto"],
+                &["proto"],
+            )?;
+
+        // Re-run if the proto file or its directory changes.
+        println!("cargo:rerun-if-changed=proto/blok/runtime/v1/runtime.proto");
+        println!("cargo:rerun-if-changed=proto");
+    }
+    Ok(())
+}

package/dist/scaffold-repo/sdks/rust/proto/blok/runtime/v1/runtime.proto

@@ -0,0 +1,302 @@
+// Blok Runtime v1 — the wire contract between the TypeScript runner and SDK
+// servers (Python, Go, Rust, Java, C#, PHP, Ruby).
+//
+// Single source of truth for cross-language interop. Generated stubs in each
+// SDK are derived from this file via `make proto`.
+//
+// Stability: `blok.runtime.v1` is additive-only. CI runs `buf breaking` to
+// reject backward-incompatible changes. Breaking changes go to `v2`, served
+// alongside `v1` during migration.
+
+syntax = "proto3";
+
+package blok.runtime.v1;
+
+option go_package          = "github.com/nickincloud/blok-go/genpb/blok/runtime/v1;runtimev1";
+option java_package        = "com.blok.runtime.v1";
+option java_multiple_files = true;
+option csharp_namespace    = "Blok.Runtime.V1";
+option php_namespace       = "Blok\\Runtime\\V1";
+option ruby_package        = "Blok::Runtime::V1";
+
+import "google/protobuf/timestamp.proto";
+
+// =============================================================================
+// Service
+// =============================================================================
+
+// NodeRuntime is the contract every Blok SDK exposes. One service handles
+// three responsibilities:
+//   1. Run a node (Execute / ExecuteStream)
+//   2. Tell the runner which nodes it can run (ListNodes)
+//   3. Tell the runner if it is alive (Health)
+service NodeRuntime {
+  // Run a node and return its result. Unary, deadline-driven.
+  rpc Execute       (ExecuteRequest)   returns (ExecuteResponse);
+
+  // Run a node and stream events back as it executes (logs, progress, partial
+  // results, then a final ExecuteResponse). Optional capability — SDKs that
+  // don't implement it should return UNIMPLEMENTED.
+  rpc ExecuteStream (ExecuteRequest)   returns (stream ExecuteEvent);
+
+  // Health check (wire-compatible with grpc.health.v1.Health/Check).
+  rpc Health        (HealthRequest)    returns (HealthResponse);
+
+  // Discover registered nodes and their schemas (drives Studio + OpenAPI gen).
+  rpc ListNodes     (ListNodesRequest) returns (ListNodesResponse);
+}
+
+// =============================================================================
+// Execute envelope (the "what we send to a node")
+// =============================================================================
+
+message ExecuteRequest {
+  // Identification: which node, what type, what version.
+  NodeRef        node     = 1;
+
+  // The node's own resolved inputs. Already mapped (js/, ${...} resolved).
+  // Bytes-encoded JSON: SDKs JSON-decode lazily. NEVER wrapped in {inputs:...}.
+  bytes          inputs   = 2;
+
+  // Where in the workflow this node sits.
+  StepInfo       step     = 3;
+
+  // The originating workflow trigger (read-only context for nodes).
+  TriggerInfo    trigger  = 4;
+
+  // Mutable state: previous step output, persistent vars, env mirror.
+  RuntimeState   state    = 5;
+
+  // Identity of the parent workflow run.
+  WorkflowInfo   workflow = 6;
+
+  // Per-call options (deadline, streaming opt-in).
+  ExecuteOptions options  = 7;
+}
+
+message NodeRef {
+  string name    = 1;   // e.g. "tutorial-store"
+  string type    = 2;   // "runtime.python3"
+  string version = 3;   // optional pin, e.g. "1.0.0"
+}
+
+message StepInfo {
+  string name  = 1;     // step name in workflow
+  int32  index = 2;     // 0-based index in current branch
+  int32  total = 3;     // total steps in current branch
+  int32  depth = 4;     // 0 = top-level; 1+ = nested in flow node (if-else)
+}
+
+message TriggerInfo {
+  // Snapshot of the trigger that started the workflow. Read-only for nodes.
+  bytes  body          = 1;            // raw bytes; encoding signaled in headers
+  map<string, string> headers = 2;
+  map<string, string> params  = 3;
+  map<string, string> query   = 4;
+  map<string, string> cookies = 5;
+  string method        = 6;
+  string url           = 7;
+  string base_url      = 8;
+  string trigger_kind  = 9;            // "http" | "worker" | "cron" | ...
+}
+
+message RuntimeState {
+  // Output of the previous step. Named explicitly so LLM-authored nodes stop
+  // confusing it with vars. Bytes-encoded JSON.
+  bytes  previous_output = 1;
+
+  // Workflow-scoped persistent storage (set_var: true on prior steps).
+  // Bytes-encoded JSON map<string, any>.
+  bytes  vars            = 2;
+
+  // String→string env mirror.
+  map<string, string> env = 3;
+}
+
+message WorkflowInfo {
+  string run_id   = 1;
+  string name     = 2;
+  string path     = 3;
+  string version  = 4;
+  google.protobuf.Timestamp started_at = 5;
+}
+
+message ExecuteOptions {
+  int64 deadline_ms     = 1;       // hard cutoff (also enforced via gRPC deadline)
+  bool  stream_logs     = 2;       // hint: caller wants ExecuteStream events
+  bool  capture_metrics = 3;
+  // Reserved for future routing/affinity hints without bumping schema.
+  map<string, string> hints = 15;
+}
+
+// =============================================================================
+// Execute response
+// =============================================================================
+
+message ExecuteResponse {
+  bool      success      = 1;
+
+  // The node's primary return value. Bytes-encoded JSON.
+  bytes     data         = 2;
+
+  // Optional content-type override (default "application/json").
+  string    content_type = 3;
+
+  // Set iff !success. Always populated on failure (see NodeError).
+  NodeError error        = 4;
+
+  // Vars the node wants persisted (merged into ctx.vars on the runner side).
+  // Optional — most nodes leave this empty and rely on workflow-level set_var.
+  // Bytes-encoded JSON map<string, any>.
+  bytes     vars_delta   = 5;
+
+  // Tail of logs captured during execution.
+  repeated  LogLine logs = 6;
+
+  // Resource usage during this call. Populated when capture_metrics=true.
+  Metrics   metrics      = 7;
+}
+
+// =============================================================================
+// Streaming variant (Phase 5 — opt-in)
+// =============================================================================
+
+message ExecuteEvent {
+  oneof event {
+    NodeStarted     started  = 1;
+    LogLine         log      = 2;
+    Progress        progress = 3;
+    PartialResult   partial  = 4;
+    ExecuteResponse final    = 5;   // last frame; closes the stream
+  }
+}
+
+message NodeStarted   { google.protobuf.Timestamp at = 1; }
+message Progress      { double percent = 1; string phase = 2; }
+message PartialResult { bytes snapshot_json = 1; }
+
+message LogLine {
+  google.protobuf.Timestamp timestamp = 1;
+  string level    = 2;            // "debug" | "info" | "warn" | "error"
+  string message  = 3;
+  map<string, string> attributes = 4;
+}
+
+// =============================================================================
+// NodeError — the structured-errors contract
+// =============================================================================
+//
+// Every node in every SDK populates a NodeError the same way. Seven required
+// fields (code, category, severity, node, at, message, http_status) plus
+// strongly-encouraged fields for richer debugging:
+// - description: multi-paragraph context (what was tried, why it failed)
+// - remediation: suggested next step (actionable)
+// - context_snapshot_json: bounded slice of inputs/state at error time
+// - causes: nested wrapped errors (e.g. an HTTP error wrapping a timeout)
+//
+// SDKs auto-fill `node`, `sdk`, `sdk_version`, `runtime_kind`, `at`, and
+// `stack` from environmental context — authors never set these manually.
+//
+// See `docs/error-codes.md` for the canonical code registry.
+
+message NodeError {
+  // === Identity ===
+  string        code        = 1;       // STABLE machine identifier (e.g. "POSTGRES_CONNECT_TIMEOUT")
+  ErrorCategory category    = 2;
+  ErrorSeverity severity    = 3;
+
+  // === Origin (auto-filled by SDK) ===
+  string        node          = 4;
+  string        sdk           = 5;     // "blok-python3"
+  string        sdk_version   = 6;
+  string        runtime_kind  = 7;     // "runtime.python3"
+  google.protobuf.Timestamp at = 8;
+
+  // === Human-readable ===
+  string        message     = 9;       // one-sentence summary
+  string        description = 10;      // multi-paragraph context
+  string        remediation = 11;      // suggested next step
+  string        doc_url     = 12;
+
+  // === Causality ===
+  repeated NodeError causes = 13;
+  string             stack  = 14;
+  bytes              context_snapshot_json = 15;
+
+  // === Compatibility / retry hints ===
+  int32  http_status     = 16;
+  bool   retryable       = 17;
+  int64  retry_after_ms  = 18;
+
+  // === Category-specific structured details ===
+  // Bytes-encoded JSON. Surfaces to GlobalError.json on the runner side.
+  bytes  details_json = 19;
+}
+
+enum ErrorCategory {
+  CATEGORY_UNSPECIFIED = 0;
+  VALIDATION    = 1;   // input/output schema mismatch
+  CONFIGURATION = 2;   // node misconfigured
+  DEPENDENCY    = 3;   // external service failed (DB, HTTP, queue)
+  TIMEOUT       = 4;
+  PERMISSION    = 5;   // auth/authz
+  RATE_LIMIT    = 6;
+  NOT_FOUND     = 7;
+  CONFLICT      = 8;
+  CANCELLED     = 9;
+  INTERNAL      = 10;  // unexpected SDK-side bug
+  PROTOCOL      = 11;  // proto/transport issue
+  DATA          = 12;  // user data malformed (not schema validation)
+}
+
+enum ErrorSeverity {
+  SEVERITY_UNSPECIFIED = 0;
+  INFO  = 1;   // expected, recoverable
+  WARN  = 2;   // anomalous but workflow continues
+  ERROR = 3;   // node failed; default
+  FATAL = 4;   // workflow should abort regardless of try/catch
+}
+
+// =============================================================================
+// Discovery
+// =============================================================================
+
+message ListNodesRequest {}
+message ListNodesResponse {
+  repeated NodeDescriptor nodes = 1;
+  string sdk_name      = 2;          // "blok-python3"
+  string sdk_version   = 3;
+  string proto_version = 4;          // "1.0.0"
+}
+
+message NodeDescriptor {
+  string name        = 1;
+  string description = 2;
+  bytes  input_schema_json  = 3;     // JSON Schema (drives OpenAPI/Studio/LLMs)
+  bytes  output_schema_json = 4;
+  repeated string tags = 5;
+}
+
+// =============================================================================
+// Health (wire-compatible with grpc.health.v1)
+// =============================================================================
+
+message HealthRequest  { string service = 1; }
+message HealthResponse {
+  enum Status { UNKNOWN = 0; SERVING = 1; NOT_SERVING = 2; }
+  Status status      = 1;
+  string sdk_version = 2;
+  repeated string registered_nodes = 3;
+}
+
+// =============================================================================
+// Metrics
+// =============================================================================
+
+message Metrics {
+  double duration_ms    = 1;
+  double cpu_ms         = 2;
+  int64  memory_bytes   = 3;
+  int64  request_bytes  = 4;
+  int64  response_bytes = 5;
+}