@telorun/http-server 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @telorun/http-server
 
+## 0.1.8
+
+### Patch Changes
+
+- Updated dependencies
+  - @telorun/sdk@0.2.8
+
+## 0.1.7
+
+### Patch Changes
+
+- Updated dependencies
+  - @telorun/sdk@0.2.7
+
 ## 0.1.5
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,17 @@
+# SUSTAINABLE USE LICENSE (Fair-code)
+
+Copyright (c) 2026 DiglyAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
+
+1. ANTI-COMPETITION RESTRICTION: The Software may not be provided to third parties as a managed service, commercial SaaS (Software-as-a-Service), PaaS (Platform-as-a-Service), BaaS (Backend-as-a-Service), or similar offering where the primary value provided to the user is the functionality of the Software itself, without a separate commercial license from the copyright holder.
+
+2. PERMITTED COMMERCIAL USE: You are free to use the Software to build, host, and monetize your own commercial applications, products, and services, provided such use does not violate Clause 1.
+
+3. ATTRIBUTION: This copyright notice and license must be included in all copies or substantial portions of the Software.
+
+4. CONTRIBUTIONS: Contributions to the Software are welcome and encouraged. By contributing, you agree that your contributions may be incorporated into the Software and distributed under this license.
+
+5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
+
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact DiglyAI.

package/README.md

@@ -0,0 +1,150 @@
+# Telo HTTP Standard Specification (v1.0 Draft)
+
+## Overview
+
+The `Http.Server` and `Http.Api` manifests in Telo are designed to be strictly **language-agnostic** and **framework-agnostic**. To maintain the "Zero Lock-in" promise, the underlying HTTP engine (e.g., Fastify in Node.js, Actix in Rust) is treated purely as an implementation detail.
+
+All HTTP modules integrated into the Telo kernel **must** adhere to this behavioral contract. This ensures that a YAML manifest written today will execute with exactly the same I/O and validation behavior regardless of the underlying language or framework.
+
+---
+
+## 1. Routing Contract (Path Definitions)
+
+Different web frameworks use different syntaxes for path parameters (e.g., `/users/:id` vs. `/users/{id}`).
+
+Telo standardizes on the **OpenAPI specification format** for paths.
+
+- **Standard:** Path parameters MUST be enclosed in curly braces: `{parameterName}`.
+- **Module Responsibility:** The underlying HTTP module must parse the Telo path and translate it into its framework's native routing syntax at startup.
+
+**Example Manifest Path:** `/api/v1/users/{userId}`
+
+- _Node.js (Fastify) Adapter translates to:_ `/api/v1/users/:userId`
+- _Rust (Actix) Adapter translates to:_ `/api/v1/users/{userId}`
+
+---
+
+## 2. The I/O Context Contract
+
+When an incoming HTTP request is received, the underlying framework must normalize it into a standard **Telo Request Object** before passing it to the Handler/CEL engine. Conversely, it must accept a standard **Telo Response Object** to send back to the client.
+
+### 2.1. Standardized Telo Request Object (Input)
+
+The HTTP module must construct and pass the following exact payload to the execution environment:
+
+```json
+{
+  "request": {
+    "method": "POST",
+    "path": "/api/v1/users/123",
+    "params": { "userId": "123" },
+    "query": { "active": "true" },
+    "headers": {
+      "content-type": "application/json",
+      "authorization": "Bearer token..."
+    },
+    "body": {
+      "name": "Alice",
+      "age": 30
+    }
+  }
+}
+```
+
+- **Constraint:** All `headers` keys MUST be normalized to lowercase.
+- **Constraint:** If the `content-type` is `application/json`, the `body` MUST be parsed into a native object/dictionary before evaluation.
+
+### 2.2. Standardized Telo Response Object (Output)
+
+After the Handler executes and the `response.mapping` evaluates, the engine will return an object to the HTTP module. The module must map this directly to the native HTTP response.
+
+```json
+{
+  "status": 200,
+  "headers": {
+    "x-telo-runtime": "0.1.0",
+    "content-type": "application/json"
+  },
+  "body": {
+    "id": "123",
+    "status": "created"
+  }
+}
+```
+
+---
+
+## 3. Validation & Error Handling Contract
+
+When a request fails schema validation (defined in the `request.schema` of the manifest), the underlying engine (e.g., AJV in Fastify) will generate native errors. **These internal errors must not leak to the client.**
+
+All Telo HTTP modules MUST intercept framework-specific validation errors and return a standardized HTTP 400 Bad Request payload.
+
+### Standardized Validation Error Format
+
+The response body must strictly follow this JSON structure:
+
+```json
+{
+  "error": "ValidationError",
+  "message": "Request validation failed",
+  "status": 400,
+  "details": [
+    {
+      "location": "body",
+      "path": "user.age",
+      "message": "must be an integer"
+    },
+    {
+      "location": "query",
+      "path": "active",
+      "message": "is a required property"
+    }
+  ]
+}
+```
+
+- **`location` enum:** `body` | `query` | `params` | `headers`
+- **Module Responsibility:** The module author must write an error handler/mapper that transforms the native framework's validation output into the Telo `details` array.
+
+---
+
+## 4. Manifest Schema Upgrades
+
+To fully support this contract, the `Http.Api` JSON Schema definition includes the following structural definitions for the `request` block:
+
+```yaml
+request:
+  type: "object"
+  properties:
+    path:
+      type: "string"
+      description: "Must use OpenAPI style path parameters, e.g., /users/{id}"
+    method:
+      type: "string"
+      enum: ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]
+    consumes:
+      type: "array"
+      items: { type: "string" }
+      default: ["application/json"]
+    produces:
+      type: "array"
+      items: { type: "string" }
+      default: ["application/json"]
+    schema:
+      type: "object"
+      properties:
+        params:
+          type: "object"
+          description: "Validation schema for path parameters"
+        query:
+          type: "object"
+          description: "Validation schema for query string parameters"
+        headers:
+          type: "object"
+          description: "Validation schema for HTTP headers"
+        body:
+          type: "object"
+          description: "Validation schema for the request payload"
+  required: ["path", "method"]
+```

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.1.6",
+  "version": "0.1.8",
+  "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
+  "keywords": [
+    "telo",
+    "http",
+    "server",
+    "api",
+    "fastify"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "modules/http-server/nodejs"
+  },
+  "homepage": "https://github.com/telorun/telo#readme",
+  "bugs": {
+    "url": "https://github.com/telorun/telo/issues"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,21 +35,21 @@
       "import": "./dist/http-api-controller.js"
     }
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.lib.json"
-  },
   "dependencies": {
     "@fastify/cors": "^11.2.0",
     "@fastify/swagger": "^9.6.1",
     "@scalar/fastify-api-reference": "^1.44.6",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/sdk": "workspace:*",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
-    "fastify": "^5.7.2"
+    "fastify": "^5.7.2",
+    "@telorun/sdk": "0.2.8"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json"
   }
-}
+}