blokctl 1.2.0 → 1.4.0

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

@@ -0,0 +1,387 @@
+# Blok Blok PHP SDK
+
+PHP SDK for building [Blok](https://github.com/deskree/blok) blok nodes. This SDK provides everything needed to create, test, and deploy workflow nodes that execute within the Blok orchestration framework.
+
+## Requirements
+
+- PHP 8.2 or later
+- Composer 2.x
+
+## Installation
+
+```bash
+composer require blok/blok-php
+```
+
+## Quick Start
+
+### 1. Create a Node
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Blok\Blok\Node\NodeHandler;
+use Blok\Blok\Types\Context;
+
+class GreetingNode implements NodeHandler
+{
+    public function execute(Context $ctx, array $config): mixed
+    {
+        $name = $ctx->request->bodyStr('name') ?? 'World';
+        $prefix = $config['prefix'] ?? 'Hello';
+
+        $message = sprintf('%s, %s!', $prefix, $name);
+        $ctx->setVar('greeting', $message);
+
+        return ['message' => $message];
+    }
+}
+```
+
+### 2. Register and Serve
+
+```php
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+use Blok\Blok\Node\NodeRegistry;
+use Blok\Blok\Server\Server;
+
+$registry = new NodeRegistry('1.0.0');
+$registry->register('greeting', new GreetingNode());
+
+$server = new Server($registry);
+$server->start();
+```
+
+### 3. Run
+
+```bash
+PORT=8080 php serve.php
+```
+
+Or with Docker:
+
+```bash
+docker build -t my-blok .
+docker run -p 8080:8080 my-blok
+```
+
+### 4. Test the Endpoint
+
+```bash
+# Health check
+curl http://localhost:8080/health
+
+# Execute a node
+curl -X POST http://localhost:8080/execute \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "node": {
+      "name": "greeting",
+      "config": {"prefix": "Hi"}
+    },
+    "context": {
+      "id": "exec-1",
+      "workflow_name": "demo",
+      "request": {
+        "body": {"name": "Blok"}
+      }
+    }
+  }'
+```
+
+## Configuration
+
+The server reads configuration from environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `8080` | HTTP server port |
+| `HOST` | `0.0.0.0` | HTTP server 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 |
+
+You can also create a `ServerConfig` programmatically:
+
+```php
+use Blok\Blok\Config\ServerConfig;
+use Blok\Blok\Logging\LogLevel;
+
+$config = new ServerConfig(
+    port: 9090,
+    host: '127.0.0.1',
+    version: '2.0.0',
+    logLevel: LogLevel::Debug,
+    enableCors: true,
+);
+
+$server = new Server($registry, $config);
+```
+
+## Middleware
+
+Middleware wraps node handlers to add cross-cutting behavior like logging, validation, or timing.
+
+### Creating Middleware
+
+```php
+use Blok\Blok\Node\NodeHandler;
+use Blok\Blok\Server\Middleware;
+use Blok\Blok\Types\Context;
+
+class TimingMiddleware implements Middleware
+{
+    public function wrap(NodeHandler $next): NodeHandler
+    {
+        return new class($next) implements NodeHandler {
+            public function __construct(private readonly NodeHandler $inner) {}
+
+            public function execute(Context $ctx, array $config): mixed
+            {
+                $start = hrtime(true);
+                $result = $this->inner->execute($ctx, $config);
+                $durationMs = (hrtime(true) - $start) / 1_000_000;
+                $ctx->setVar('execution_time_ms', $durationMs);
+                return $result;
+            }
+        };
+    }
+}
+```
+
+### Applying Middleware
+
+```php
+$registry = new NodeRegistry('1.0.0');
+$registry->register('my-node', new MyNode());
+$registry->useMiddleware(new TimingMiddleware());
+```
+
+Middleware is applied in registration order. The last registered middleware wraps outermost.
+
+## Schema Validation
+
+Validate data against JSON Schema (Draft 7 subset):
+
+```php
+use Blok\Blok\Validation\SchemaValidator;
+
+$validator = new SchemaValidator();
+$errors = $validator->validate($data, [
+    'type' => 'object',
+    'required' => ['name', 'email'],
+    'properties' => [
+        'name' => ['type' => 'string', 'minLength' => 1, 'maxLength' => 100],
+        'email' => ['type' => 'string'],
+        'age' => ['type' => 'integer', 'minimum' => 0, 'maximum' => 150],
+        'tags' => ['type' => 'array', 'items' => ['type' => 'string'], 'minItems' => 1],
+    ],
+]);
+
+if (!empty($errors)) {
+    throw NodeException::validation('Invalid input', $errors);
+}
+```
+
+Supported schema keywords: `type`, `required`, `properties`, `enum`, `minLength`, `maxLength`, `minimum`, `maximum`, `items`, `minItems`, `maxItems`.
+
+## Logging
+
+Capture structured logs that are returned in the `ExecutionResult.logs` field:
+
+```php
+use Blok\Blok\Logging\Logger;
+use Blok\Blok\Logging\LogLevel;
+
+$logger = new Logger(LogLevel::Debug);
+$logger->info('Processing request');
+$logger->debugWith('Request details', ['method' => 'POST', 'path' => '/api']);
+$logger->warn('Deprecated field used');
+$logger->errorWith('Failed to connect', ['host' => 'api.example.com']);
+
+// Get formatted log lines for ExecutionResult
+$result->withLogs($logger->lines());
+```
+
+## Error Handling
+
+Use `NodeException` for structured errors with categories:
+
+```php
+use Blok\Blok\Errors\NodeException;
+
+// Factory methods create exceptions with appropriate codes
+throw NodeException::validation('Name is required');     // 400
+throw NodeException::execution('Processing failed');     // 500
+throw NodeException::configuration('Missing API key');   // 500
+throw NodeException::network('Connection timed out');    // 502
+throw NodeException::notFound('User not found');         // 404
+
+// With details
+throw NodeException::validation('Invalid fields', [
+    'name' => 'must not be empty',
+    'email' => 'invalid format',
+]);
+```
+
+## Testing
+
+The SDK includes testing utilities for unit testing nodes without starting a server.
+
+### Using MockContext
+
+```php
+use Blok\Blok\Testing\MockContext;
+
+$ctx = MockContext::create()
+    ->withId('test-1')
+    ->withWorkflow('my-workflow', '/workflows/my')
+    ->withBody(['name' => 'Test User', 'email' => 'test@example.com'])
+    ->withHeaders(['Authorization' => 'Bearer token'])
+    ->withVar('previous_result', ['status' => 'ok'])
+    ->withEnv('API_KEY', 'test-key')
+    ->build();
+```
+
+### Using TestRunner
+
+```php
+use Blok\Blok\Testing\MockContext;
+use Blok\Blok\Testing\TestRunner;
+
+$runner = new TestRunner();
+$runner->register('greeting', new GreetingNode());
+
+$ctx = MockContext::create()
+    ->withBody(['name' => 'PHPUnit'])
+    ->build();
+
+$result = $runner->execute('greeting', $ctx, ['prefix' => 'Hi']);
+
+// Assert helpers
+$data = TestRunner::assertSuccess($result);
+$this->assertEquals('Hi, PHPUnit!', $data['message']);
+```
+
+### PHPUnit Example
+
+```php
+use PHPUnit\Framework\TestCase;
+use Blok\Blok\Testing\MockContext;
+
+class GreetingNodeTest extends TestCase
+{
+    public function testDefaultGreeting(): void
+    {
+        $node = new GreetingNode();
+        $ctx = MockContext::create()->build();
+        $result = $node->execute($ctx, []);
+
+        $this->assertEquals('Hello, World!', $result['message']);
+    }
+
+    public function testCustomName(): void
+    {
+        $node = new GreetingNode();
+        $ctx = MockContext::create()
+            ->withBody(['name' => 'Blok'])
+            ->build();
+        $result = $node->execute($ctx, []);
+
+        $this->assertEquals('Hello, Blok!', $result['message']);
+    }
+}
+```
+
+## HTTP Protocol
+
+The blok runtime exposes two endpoints:
+
+### POST /execute
+
+Receives an `ExecutionRequest` and returns an `ExecutionResult` (always HTTP 200).
+
+**Request:**
+```json
+{
+  "node": {
+    "name": "hello-world",
+    "path": "",
+    "type": "",
+    "config": {}
+  },
+  "context": {
+    "id": "exec-123",
+    "workflow_name": "my-workflow",
+    "workflow_path": "/workflows/my",
+    "request": {
+      "body": {},
+      "headers": {},
+      "params": {},
+      "query": {},
+      "method": "POST",
+      "url": "/api/endpoint"
+    },
+    "response": {},
+    "vars": {},
+    "env": {}
+  }
+}
+```
+
+**Response (success):**
+```json
+{
+  "success": true,
+  "data": {"message": "Hello, World!"},
+  "metrics": {
+    "duration_ms": 1.234,
+    "memory_bytes": 2097152
+  }
+}
+```
+
+**Response (error):**
+```json
+{
+  "success": false,
+  "data": null,
+  "errors": {"message": "node 'unknown' not found in registry"}
+}
+```
+
+### GET /health
+
+Returns the runtime health status.
+
+```json
+{
+  "status": "healthy",
+  "version": "1.0.0",
+  "nodes_loaded": ["hello-world", "api-call", "transform-data"]
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+composer install
+
+# Run tests
+composer test
+
+# Start the example server
+composer serve
+```
+
+## License
+
+MIT

package/dist/scaffold-repo/sdks/php/composer.json

@@ -0,0 +1,41 @@
+{
+	"name": "blok/blok-php",
+	"description": "PHP SDK for building Blok blok nodes",
+	"type": "library",
+	"license": "MIT",
+	"keywords": ["blok", "blok", "workflow", "microservice", "node"],
+	"require": {
+		"php": ">=8.2",
+		"react/http": "^1.9",
+		"react/socket": "^1.15",
+		"google/protobuf": "^4.33",
+		"spiral/roadrunner-grpc": "^3.5"
+	},
+	"require-dev": {
+		"phpunit/phpunit": "^10"
+	},
+	"autoload": {
+		"psr-4": {
+			"Blok\\Blok\\": "src/",
+			"Blok\\Blok\\Examples\\": "examples/",
+			"Blok\\Runtime\\V1\\": "src/Genpb/Blok/Runtime/V1/",
+			"GPBMetadata\\Blok\\Runtime\\V1\\": "src/Genpb/GPBMetadata/Blok/Runtime/V1/"
+		}
+	},
+	"autoload-dev": {
+		"psr-4": {
+			"Blok\\Blok\\Tests\\": "tests/"
+		}
+	},
+	"scripts": {
+		"test": "phpunit",
+		"serve": "php bin/serve.php"
+	},
+	"config": {
+		"sort-packages": true,
+		"audit": {
+			"ignore": ["PKSA-xbp4-qwr2-cbjj"]
+		}
+	},
+	"minimum-stability": "stable"
+}

package/dist/scaffold-repo/sdks/php/examples/ApiCallNode.php

@@ -0,0 +1,103 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Examples;
+
+use Blok\Blok\Errors\NodeException;
+use Blok\Blok\Node\NodeHandler;
+use Blok\Blok\Types\Context;
+
+/**
+ * ApiCallNode makes HTTP requests to external APIs.
+ *
+ * Config:
+ *   - url (string, required): The URL to call
+ *   - method (string, optional): HTTP method (default: GET)
+ *   - timeout (int, optional): Timeout in seconds (default: 10)
+ *   - headers (object, optional): Additional headers to send
+ *
+ * Body (for POST/PUT/PATCH):
+ *   - body (mixed, optional): Request body to send
+ */
+final class ApiCallNode implements NodeHandler
+{
+    public function execute(Context $ctx, array $config): mixed
+    {
+        $url = $config['url'] ?? null;
+        if (!is_string($url) || $url === '') {
+            throw NodeException::configuration("'url' is required in node config");
+        }
+
+        $method = strtoupper((string) ($config['method'] ?? 'GET'));
+        $timeout = (int) ($config['timeout'] ?? 10);
+
+        // Build HTTP context options
+        $httpOptions = [
+            'method' => $method,
+            'timeout' => $timeout,
+            'ignore_errors' => true,
+            'header' => "Content-Type: application/json\r\n",
+        ];
+
+        // Add custom headers from config
+        if (isset($config['headers']) && is_array($config['headers'])) {
+            foreach ($config['headers'] as $key => $value) {
+                if (is_string($value)) {
+                    $httpOptions['header'] .= sprintf("%s: %s\r\n", $key, $value);
+                }
+            }
+        }
+
+        // Add body for POST/PUT/PATCH
+        if (in_array($method, ['POST', 'PUT', 'PATCH'], true)) {
+            $body = is_array($ctx->request->body) ? ($ctx->request->body['body'] ?? null) : null;
+            if ($body !== null) {
+                $httpOptions['content'] = json_encode($body, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
+            }
+        }
+
+        $streamContext = stream_context_create([
+            'http' => $httpOptions,
+            'ssl' => [
+                'verify_peer' => true,
+                'verify_peer_name' => true,
+            ],
+        ]);
+
+        $responseBody = @file_get_contents($url, false, $streamContext);
+
+        if ($responseBody === false) {
+            throw NodeException::network(sprintf('request to %s failed', $url));
+        }
+
+        // Parse status code from response headers
+        $statusCode = 200;
+        $responseHeaders = [];
+        $rawHeaders = http_get_last_response_headers();
+        if (is_array($rawHeaders)) {
+            foreach ($rawHeaders as $header) {
+                if (preg_match('/^HTTP\/[\d.]+ (\d{3})/', $header, $matches)) {
+                    $statusCode = (int) $matches[1];
+                } else {
+                    $parts = explode(':', $header, 2);
+                    if (count($parts) === 2) {
+                        $responseHeaders[strtolower(trim($parts[0]))] = trim($parts[1]);
+                    }
+                }
+            }
+        }
+
+        // Try to parse response as JSON, fall back to string
+        $data = json_decode($responseBody, true);
+        if (json_last_error() !== JSON_ERROR_NONE) {
+            $data = $responseBody;
+        }
+
+        return [
+            'status' => $statusCode,
+            'data' => $data,
+            'headers' => $responseHeaders,
+        ];
+    }
+}

package/dist/scaffold-repo/sdks/php/examples/BlokErrorDemoNode.php

@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Examples;
+
+use Blok\Blok\Errors\BlokError;
+use Blok\Blok\Errors\BuildContextSnapshot;
+use Blok\Blok\Node\NodeHandler;
+use Blok\Blok\Types\Context;
+
+/**
+ * Example node demonstrating the structured {@see BlokError} API per master
+ * plan §17.
+ *
+ * Used by the cross-language E2E test
+ * (`core/runner/__tests__/integration/runtimes/php-grpc.integration.test.ts`)
+ * to verify that a PHP-side structured error flows through the gRPC wire to
+ * the runner with every field preserved (category, severity, code,
+ * remediation, retryable hints, cause chain, context snapshot).
+ *
+ * Triggered via the `mode` config:
+ * - `mode = "dependency"` (default) — throws `BlokError::dependency()` with
+ *   a cause chain rooted in a {@see \RuntimeException}.
+ * - `mode = "rate-limit"` — throws `BlokError::rateLimit()` with
+ *   `retry_after_ms`.
+ * - `mode = "validation"` — throws `BlokError::validation()` with
+ *   `details["issues"]`.
+ * - `mode = "ok"` — returns success.
+ */
+final class BlokErrorDemoNode implements NodeHandler
+{
+    public function execute(Context $ctx, array $config): mixed
+    {
+        $mode = $config['mode'] ?? 'dependency';
+        if (!is_string($mode)) {
+            $mode = 'dependency';
+        }
+
+        if ($mode === 'ok') {
+            return ['ok' => true, 'language' => 'php'];
+        }
+
+        $snapshot = BuildContextSnapshot::of($config, $ctx->vars ?? []);
+
+        if ($mode === 'rate-limit') {
+            throw BlokError::rateLimit()
+                ->code('UPSTREAM_RATE_LIMITED')
+                ->message('Upstream API returned 429')
+                ->description('GitHub API rate limit hit (5000 req/hr).')
+                ->remediation('Wait until the X-RateLimit-Reset header timestamp.')
+                ->retryAfterMs(60000)
+                ->docUrl('https://docs.example.com/errors/rate-limit')
+                ->details(['limit' => 5000, 'remaining' => 0])
+                ->contextSnapshot($snapshot)
+                ->build();
+        }
+
+        if ($mode === 'validation') {
+            throw BlokError::validation()
+                ->code('VALIDATION_FAILED')
+                ->message('2 validation issues')
+                ->description("Inputs didn't match the node's schema.")
+                ->remediation('Provide both `email` and `name`.')
+                ->details([
+                    'issues' => [
+                        ['path' => ['email'], 'message' => 'Required'],
+                        ['path' => ['name'],  'message' => 'Required'],
+                    ],
+                ])
+                ->contextSnapshot($snapshot)
+                ->build();
+        }
+
+        // default: dependency with a cause chain rooted in a RuntimeException.
+        $cause = new \RuntimeException('[Errno 61] Connection refused');
+        throw BlokError::dependency()
+            ->code('POSTGRES_CONNECT_TIMEOUT')
+            ->message('Could not connect to Postgres within 5s')
+            ->description('Tried host=db.internal port=5432; timeout=5000ms')
+            ->remediation('Check DATABASE_URL env var and network reachability')
+            ->cause($cause)
+            ->retryable(true)
+            ->retryAfterMs(5000)
+            ->docUrl('https://docs.example.com/errors/POSTGRES_CONNECT_TIMEOUT')
+            ->details(['host' => 'db.internal', 'port' => 5432, 'timeout_ms' => 5000])
+            ->contextSnapshot($snapshot)
+            ->build();
+    }
+}

package/dist/scaffold-repo/sdks/php/examples/ChainTestNode.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Examples;
+
+use Blok\Blok\Node\NodeHandler;
+use Blok\Blok\Types\Context;
+
+/**
+ * ChainTestNode is used in cross-runtime integration tests.
+ * It reads a chain array from the request body, appends its own entry,
+ * and returns the updated chain — proving data flows between languages.
+ */
+final class ChainTestNode implements NodeHandler
+{
+    public function execute(Context $ctx, array $config): mixed
+    {
+        $body = $ctx->request->body;
+
+        // Read existing chain — gRPC inputs first (carried on
+        // `node.config`), HTTP body fallback (legacy wire shape where
+        // the runner mapped resolvedInputs → request.body). Dual-read
+        // keeps the cross-runtime-chain demo working over both
+        // transports during the §11 deprecation window.
+        $chain = [];
+        if (isset($config['chain']) && is_array($config['chain'])) {
+            $chain = $config['chain'];
+        } elseif (is_array($body) && isset($body['chain']) && is_array($body['chain'])) {
+            $chain = $body['chain'];
+        }
+
+        // Read origin — same dual-read.
+        $origin = 'unknown';
+        if (isset($config['origin']) && is_string($config['origin']) && $config['origin'] !== '') {
+            $origin = $config['origin'];
+        } elseif (is_array($body) && isset($body['origin']) && is_string($body['origin'])) {
+            $origin = $body['origin'];
+        }
+
+        // Append this language's entry
+        $chain[] = [
+            'language' => 'php',
+            'order' => count($chain) + 1,
+            'timestamp' => gmdate('Y-m-d\TH:i:s\Z'),
+        ];
+
+        // Store in context vars
+        $ctx->setVar('chain', $chain);
+
+        return [
+            'chain' => $chain,
+            'origin' => $origin,
+        ];
+    }
+}