blokctl 1.2.0 → 1.4.0

package/dist/scaffold-repo/sdks/php/src/Server/Server.php

@@ -0,0 +1,157 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Server;
+
+use Blok\Blok\Config\ServerConfig;
+use Blok\Blok\Node\NodeRegistry;
+use Blok\Blok\Types\ExecutionRequest;
+use Psr\Http\Message\ServerRequestInterface;
+use React\Http\HttpServer;
+use React\Http\Message\Response as HttpResponse;
+use React\Http\Middleware\RequestBodyBufferMiddleware;
+use React\Http\Middleware\RequestBodyParserMiddleware;
+use React\Http\Middleware\StreamingRequestMiddleware;
+use React\Socket\SocketServer;
+
+/**
+ * Server is the HTTP server that handles /execute and /health endpoints
+ * using ReactPHP for non-blocking I/O.
+ */
+final class Server
+{
+    private readonly ServerConfig $config;
+
+    public function __construct(
+        private readonly NodeRegistry $registry,
+        ?ServerConfig $config = null,
+    ) {
+        $this->config = $config ?? ServerConfig::fromEnv();
+    }
+
+    /**
+     * Start the HTTP server. This is a blocking call.
+     */
+    public function start(): void
+    {
+        // Explicit middleware chain with 16 MB body buffer.
+        // Without this, ReactPHP's default 64 KB socket buffer silently truncates
+        // large request bodies (common when ctx.vars accumulates data across steps).
+        $server = new HttpServer(
+            new StreamingRequestMiddleware(),
+            new RequestBodyBufferMiddleware(16 * 1024 * 1024), // 16 MB
+            new RequestBodyParserMiddleware(),
+            function (ServerRequestInterface $request): HttpResponse {
+                return $this->handleRequest($request);
+            }
+        );
+
+        $address = sprintf('%s:%d', $this->config->host, $this->config->port);
+        $socket = new SocketServer($address);
+        $server->listen($socket);
+
+        echo sprintf(
+            "Blok blok runtime v%s listening on %s\n",
+            $this->config->version,
+            $address,
+        );
+    }
+
+    /**
+     * Handle an incoming HTTP request.
+     */
+    private function handleRequest(ServerRequestInterface $request): HttpResponse
+    {
+        $path = $request->getUri()->getPath();
+        $method = strtoupper($request->getMethod());
+
+        $headers = ['Content-Type' => 'application/json'];
+
+        if ($this->config->enableCors) {
+            $headers['Access-Control-Allow-Origin'] = '*';
+            $headers['Access-Control-Allow-Methods'] = 'GET, POST, OPTIONS';
+            $headers['Access-Control-Allow-Headers'] = 'Content-Type';
+        }
+
+        // Handle CORS preflight
+        if ($method === 'OPTIONS' && $this->config->enableCors) {
+            return new HttpResponse(204, $headers, '');
+        }
+
+        return match ($path) {
+            '/execute' => $this->handleExecute($request, $method, $headers),
+            '/health' => $this->handleHealth($method, $headers),
+            default => $this->jsonResponse(404, ['error' => 'not found'], $headers),
+        };
+    }
+
+    /**
+     * Handle POST /execute.
+     */
+    private function handleExecute(
+        ServerRequestInterface $request,
+        string $method,
+        array $headers,
+    ): HttpResponse {
+        if ($method !== 'POST') {
+            return $this->jsonResponse(405, ['error' => 'method not allowed'], $headers);
+        }
+
+        $body = (string) $request->getBody();
+        $expectedLength = (int) $request->getHeaderLine('Content-Length');
+        $actualLength = strlen($body);
+
+        // Detect Content-Length vs actual body mismatch (e.g. body truncated by buffer limit)
+        if ($actualLength === 0 && $expectedLength > 0) {
+            return $this->jsonResponse(400, [
+                'success' => false,
+                'data' => null,
+                'errors' => [
+                    'message' => sprintf(
+                        'Empty body received (Content-Length: %d, actual: 0). '
+                        . 'This usually means the request exceeded the body buffer limit.',
+                        $expectedLength,
+                    ),
+                ],
+            ], $headers);
+        }
+
+        $data = json_decode($body, true);
+
+        if (json_last_error() !== JSON_ERROR_NONE || !is_array($data)) {
+            return $this->jsonResponse(400, [
+                'success' => false,
+                'data' => null,
+                'errors' => ['message' => 'invalid JSON: ' . json_last_error_msg()],
+            ], $headers);
+        }
+
+        $execRequest = ExecutionRequest::fromArray($data);
+        $result = $this->registry->execute($execRequest);
+
+        return $this->jsonResponse(200, $result->toArray(), $headers);
+    }
+
+    /**
+     * Handle GET /health.
+     */
+    private function handleHealth(string $method, array $headers): HttpResponse
+    {
+        if ($method !== 'GET') {
+            return $this->jsonResponse(405, ['error' => 'method not allowed'], $headers);
+        }
+
+        $health = $this->registry->health();
+        return $this->jsonResponse(200, $health->toArray(), $headers);
+    }
+
+    /**
+     * Create a JSON HTTP response.
+     */
+    private function jsonResponse(int $status, array $data, array $headers): HttpResponse
+    {
+        $json = json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
+        return new HttpResponse($status, $headers, $json ?: '{}');
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Testing/MockContext.php

@@ -0,0 +1,161 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Testing;
+
+use Blok\Blok\Types\Context;
+use Blok\Blok\Types\Request;
+use Blok\Blok\Types\Response;
+
+/**
+ * MockContext provides a fluent builder for creating test Context instances.
+ */
+final class MockContext
+{
+    private string $id = 'test-execution-id';
+    private string $workflowName = 'test-workflow';
+    private string $workflowPath = '/workflows/test';
+    private mixed $body = [];
+    /** @var array<string, string> */
+    private array $headers = [];
+    private string $method = 'POST';
+    private string $url = '/test';
+    /** @var array<string, mixed> */
+    private array $vars = [];
+    /** @var array<string, string> */
+    private array $env = [];
+    /** @var array<string, string> */
+    private array $params = [];
+    /** @var array<string, string> */
+    private array $query = [];
+
+    /**
+     * Create a new MockContext builder.
+     */
+    public static function create(): self
+    {
+        return new self();
+    }
+
+    /**
+     * Set the execution ID.
+     */
+    public function withId(string $id): self
+    {
+        $this->id = $id;
+        return $this;
+    }
+
+    /**
+     * Set the workflow name and path.
+     */
+    public function withWorkflow(string $name, string $path): self
+    {
+        $this->workflowName = $name;
+        $this->workflowPath = $path;
+        return $this;
+    }
+
+    /**
+     * Set the request body.
+     */
+    public function withBody(mixed $body): self
+    {
+        $this->body = $body;
+        return $this;
+    }
+
+    /**
+     * Set the request headers.
+     *
+     * @param array<string, string> $headers
+     */
+    public function withHeaders(array $headers): self
+    {
+        $this->headers = $headers;
+        return $this;
+    }
+
+    /**
+     * Set the request method.
+     */
+    public function withMethod(string $method): self
+    {
+        $this->method = $method;
+        return $this;
+    }
+
+    /**
+     * Set the request URL.
+     */
+    public function withUrl(string $url): self
+    {
+        $this->url = $url;
+        return $this;
+    }
+
+    /**
+     * Set a context variable.
+     */
+    public function withVar(string $key, mixed $value): self
+    {
+        $this->vars[$key] = $value;
+        return $this;
+    }
+
+    /**
+     * Set an environment variable.
+     */
+    public function withEnv(string $key, string $value): self
+    {
+        $this->env[$key] = $value;
+        return $this;
+    }
+
+    /**
+     * Set request params.
+     *
+     * @param array<string, string> $params
+     */
+    public function withParams(array $params): self
+    {
+        $this->params = $params;
+        return $this;
+    }
+
+    /**
+     * Set request query parameters.
+     *
+     * @param array<string, string> $query
+     */
+    public function withQuery(array $query): self
+    {
+        $this->query = $query;
+        return $this;
+    }
+
+    /**
+     * Build the Context instance.
+     */
+    public function build(): Context
+    {
+        return new Context(
+            id: $this->id,
+            workflowName: $this->workflowName,
+            workflowPath: $this->workflowPath,
+            request: new Request(
+                body: $this->body,
+                headers: $this->headers,
+                params: $this->params,
+                query: $this->query,
+                method: $this->method,
+                url: $this->url,
+                baseUrl: 'http://localhost:8080',
+            ),
+            response: new Response(),
+            vars: $this->vars,
+            env: $this->env,
+        );
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Testing/TestRunner.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Testing;
+
+use Blok\Blok\Node\NodeHandler;
+use Blok\Blok\Node\NodeRegistry;
+use Blok\Blok\Types\Context;
+use Blok\Blok\Types\ExecutionRequest;
+use Blok\Blok\Types\ExecutionResult;
+use Blok\Blok\Types\NodeConfig;
+
+/**
+ * TestRunner executes nodes in-process for testing.
+ */
+final class TestRunner
+{
+    private readonly NodeRegistry $registry;
+
+    public function __construct()
+    {
+        $this->registry = new NodeRegistry('test');
+    }
+
+    /**
+     * Register a node for testing.
+     */
+    public function register(string $name, NodeHandler $handler): self
+    {
+        $this->registry->register($name, $handler);
+        return $this;
+    }
+
+    /**
+     * Execute a node with the given context and config.
+     *
+     * @param array<string, mixed> $config
+     */
+    public function execute(string $name, Context $ctx, array $config = []): ExecutionResult
+    {
+        $req = new ExecutionRequest(
+            node: new NodeConfig(
+                name: $name,
+                config: $config,
+            ),
+            context: $ctx,
+        );
+
+        return $this->registry->execute($req);
+    }
+
+    /**
+     * Assert that a result is successful and return the data.
+     */
+    public static function assertSuccess(ExecutionResult $result): mixed
+    {
+        if (!$result->success) {
+            throw new \RuntimeException(
+                sprintf('Expected success but got error: %s', json_encode($result->errors))
+            );
+        }
+        return $result->data;
+    }
+
+    /**
+     * Assert that a result is an error and return the error value.
+     */
+    public static function assertError(ExecutionResult $result): mixed
+    {
+        if ($result->success) {
+            throw new \RuntimeException(
+                sprintf('Expected error but got success: %s', json_encode($result->data))
+            );
+        }
+        return $result->errors;
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Types/Context.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Types;
+
+/**
+ * Context represents the workflow execution context passed between nodes.
+ */
+final class Context
+{
+    public function __construct(
+        public string $id = '',
+        public string $workflowName = '',
+        public string $workflowPath = '',
+        public Request $request = new Request(),
+        public Response $response = new Response(),
+        /** @var array<string, mixed> */
+        public array $vars = [],
+        /** @var array<string, string> */
+        public array $env = [],
+    ) {}
+
+    /**
+     * Store a variable in context for downstream nodes.
+     */
+    public function setVar(string $key, mixed $value): void
+    {
+        $this->vars[$key] = $value;
+    }
+
+    /**
+     * Retrieve a variable from context.
+     */
+    public function getVar(string $key): mixed
+    {
+        return $this->vars[$key] ?? null;
+    }
+
+    /**
+     * Retrieve a string variable from context.
+     */
+    public function getVarStr(string $key): ?string
+    {
+        $val = $this->vars[$key] ?? null;
+        return is_string($val) ? $val : null;
+    }
+
+    /**
+     * Create a Context from an associative array.
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            id: $data['id'] ?? '',
+            workflowName: $data['workflow_name'] ?? '',
+            workflowPath: $data['workflow_path'] ?? '',
+            request: isset($data['request']) ? Request::fromArray($data['request']) : new Request(),
+            response: isset($data['response']) ? Response::fromArray($data['response']) : new Response(),
+            vars: $data['vars'] ?? [],
+            env: $data['env'] ?? [],
+        );
+    }
+
+    /**
+     * Convert to an associative array for JSON serialization.
+     */
+    public function toArray(): array
+    {
+        return [
+            'id' => $this->id,
+            'workflow_name' => $this->workflowName,
+            'workflow_path' => $this->workflowPath,
+            'request' => $this->request->toArray(),
+            'response' => $this->response->toArray(),
+            'vars' => $this->vars,
+            'env' => $this->env,
+        ];
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Types/ExecutionMetrics.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Types;
+
+/**
+ * ExecutionMetrics captures performance metrics for a node execution.
+ */
+final class ExecutionMetrics
+{
+    public function __construct(
+        public ?float $durationMs = null,
+        public ?float $cpuMs = null,
+        public ?int $memoryBytes = null,
+    ) {}
+
+    /**
+     * Create an ExecutionMetrics from an associative array.
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            durationMs: $data['duration_ms'] ?? null,
+            cpuMs: $data['cpu_ms'] ?? null,
+            memoryBytes: isset($data['memory_bytes']) ? (int) $data['memory_bytes'] : null,
+        );
+    }
+
+    /**
+     * Convert to an associative array for JSON serialization.
+     * Omits null values.
+     */
+    public function toArray(): array
+    {
+        $result = [];
+        if ($this->durationMs !== null) {
+            $result['duration_ms'] = $this->durationMs;
+        }
+        if ($this->cpuMs !== null) {
+            $result['cpu_ms'] = $this->cpuMs;
+        }
+        if ($this->memoryBytes !== null) {
+            $result['memory_bytes'] = $this->memoryBytes;
+        }
+        return $result;
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Types/ExecutionRequest.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Types;
+
+/**
+ * ExecutionRequest is the request received from the Blok runner.
+ */
+final class ExecutionRequest
+{
+    public function __construct(
+        public NodeConfig $node = new NodeConfig(),
+        public Context $context = new Context(),
+    ) {}
+
+    /**
+     * Create an ExecutionRequest from an associative array.
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            node: isset($data['node']) ? NodeConfig::fromArray($data['node']) : new NodeConfig(),
+            context: isset($data['context']) ? Context::fromArray($data['context']) : new Context(),
+        );
+    }
+
+    /**
+     * Convert to an associative array for JSON serialization.
+     */
+    public function toArray(): array
+    {
+        return [
+            'node' => $this->node->toArray(),
+            'context' => $this->context->toArray(),
+        ];
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Types/ExecutionResult.php

@@ -0,0 +1,143 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Types;
+
+/**
+ * ExecutionResult is the response returned to the Blok runner.
+ */
+final class ExecutionResult
+{
+    public function __construct(
+        public bool $success = false,
+        public mixed $data = null,
+        public mixed $errors = null,
+        /** @var string[]|null */
+        public ?array $logs = null,
+        public ?ExecutionMetrics $metrics = null,
+        /** @var array<string, mixed>|null */
+        public ?array $vars = null,
+    ) {}
+
+    /**
+     * Create a successful result.
+     */
+    public static function success(mixed $data): self
+    {
+        return new self(
+            success: true,
+            data: $data,
+        );
+    }
+
+    /**
+     * Create a successful result with metrics.
+     */
+    public static function successWithMetrics(mixed $data, ExecutionMetrics $metrics): self
+    {
+        return new self(
+            success: true,
+            data: $data,
+            metrics: $metrics,
+        );
+    }
+
+    /**
+     * Create an error result.
+     */
+    public static function error(string $message): self
+    {
+        return new self(
+            success: false,
+            data: null,
+            errors: ['message' => $message],
+        );
+    }
+
+    /**
+     * Create an error result with details.
+     */
+    public static function errorWithDetails(string $message, mixed $details): self
+    {
+        return new self(
+            success: false,
+            data: null,
+            errors: [
+                'message' => $message,
+                'details' => $details,
+            ],
+        );
+    }
+
+    /**
+     * Attach log entries to the result.
+     */
+    public function withLogs(array $logs): self
+    {
+        $this->logs = $logs;
+        return $this;
+    }
+
+    /**
+     * Attach metrics to the result.
+     */
+    public function withMetrics(ExecutionMetrics $metrics): self
+    {
+        $this->metrics = $metrics;
+        return $this;
+    }
+
+    /**
+     * Attach context variables to the result.
+     *
+     * @param array<string, mixed> $vars
+     */
+    public function withVars(array $vars): self
+    {
+        $this->vars = $vars;
+        return $this;
+    }
+
+    /**
+     * Create an ExecutionResult from an associative array.
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            success: $data['success'] ?? false,
+            data: $data['data'] ?? null,
+            errors: $data['errors'] ?? null,
+            logs: $data['logs'] ?? null,
+            metrics: isset($data['metrics']) ? ExecutionMetrics::fromArray($data['metrics']) : null,
+            vars: $data['vars'] ?? null,
+        );
+    }
+
+    /**
+     * Convert to an associative array for JSON serialization.
+     * Omits null optional fields.
+     */
+    public function toArray(): array
+    {
+        $result = [
+            'success' => $this->success,
+            'data' => $this->data,
+        ];
+
+        if ($this->errors !== null) {
+            $result['errors'] = $this->errors;
+        }
+        if ($this->logs !== null) {
+            $result['logs'] = $this->logs;
+        }
+        if ($this->metrics !== null) {
+            $result['metrics'] = $this->metrics->toArray();
+        }
+        if ($this->vars !== null) {
+            $result['vars'] = $this->vars;
+        }
+
+        return $result;
+    }
+}