@onlineapps/service-wrapper 2.0.6 → 2.0.8

package/docs/OPERATIONS_SCHEMA.md

@@ -0,0 +1,363 @@
+# Operations Schema Specification
+
+## Overview
+
+The Operations Schema replaces OpenAPI for internal microservices, providing a simpler, more focused specification for service operations that map directly to Cookbook workflow steps.
+
+## Why Operations Schema?
+
+- **Simpler than OpenAPI** - Only what's needed for workflow orchestration
+- **Direct Cookbook mapping** - Operations correspond 1:1 with workflow steps
+- **Flexible execution** - Supports both direct function calls and HTTP
+- **Extensible** - Easy to add support for external APIs (REST, GraphQL, gRPC)
+
+## File Location
+
+Operations are defined in `/conn-config/operations.json` for each service.
+
+## Schema Structure
+
+### Basic Operation (Internal Service)
+
+```json
+{
+  "operations": {
+    "operation-name": {
+      "description": "Human-readable description",
+      "handler": "path.to.handler.function",
+      "endpoint": "/api/operation-name",
+      "method": "POST",
+      "input": {
+        "field1": {
+          "type": "string",
+          "required": true,
+          "description": "Field description"
+        },
+        "field2": {
+          "type": "number",
+          "default": 0
+        }
+      },
+      "output": {
+        "result": {
+          "type": "string",
+          "description": "Result description"
+        },
+        "timestamp": {
+          "type": "datetime"
+        }
+      }
+    }
+  }
+}
+```
+
+### External REST API Operation
+
+```json
+{
+  "operations": {
+    "send-email": {
+      "description": "Send email via SendGrid",
+      "handler": "handlers.email.send",
+      "external": {
+        "type": "rest",
+        "endpoint": "https://api.sendgrid.com/v3/mail/send",
+        "method": "POST",
+        "headers": {
+          "Authorization": "Bearer ${SENDGRID_API_KEY}",
+          "Content-Type": "application/json"
+        },
+        "mapping": {
+          "input": {
+            "personalizations[0].to[0].email": "$.recipient",
+            "from.email": "${SENDER_EMAIL}",
+            "subject": "$.subject",
+            "content[0].value": "$.body"
+          },
+          "output": {
+            "messageId": "$.x-message-id",
+            "status": "$.status"
+          }
+        }
+      },
+      "input": {
+        "recipient": { "type": "string", "required": true },
+        "subject": { "type": "string", "required": true },
+        "body": { "type": "string", "required": true }
+      },
+      "output": {
+        "messageId": "string",
+        "status": "string"
+      }
+    }
+  }
+}
+```
+
+### GraphQL Operation
+
+```json
+{
+  "operations": {
+    "get-user-repos": {
+      "description": "Get user repositories from GitHub",
+      "external": {
+        "type": "graphql",
+        "endpoint": "https://api.github.com/graphql",
+        "headers": {
+          "Authorization": "Bearer ${GITHUB_TOKEN}"
+        },
+        "query": "query($login: String!) { user(login: $login) { repositories(first: 10) { nodes { name, description } } } }",
+        "variables": {
+          "login": "$.username"
+        },
+        "mapping": {
+          "output": {
+            "repositories": "$.data.user.repositories.nodes"
+          }
+        }
+      },
+      "input": {
+        "username": { "type": "string", "required": true }
+      },
+      "output": {
+        "repositories": { "type": "array" }
+      }
+    }
+  }
+}
+```
+
+## Field Types
+
+Supported types for input/output fields:
+
+- `string` - Text data
+- `number` - Numeric value (integer or float)
+- `boolean` - True/false
+- `object` - Nested object structure
+- `array` - Array of items
+- `datetime` - ISO 8601 datetime string
+- `date` - ISO 8601 date string
+- `email` - Email address (validated)
+- `url` - URL (validated)
+- `uuid` - UUID v4 (validated)
+
+## Execution Modes
+
+Services can run in different execution modes, configured in `config.json`:
+
+### Direct Mode (Internal Services)
+```json
+{
+  "service": {
+    "execution": {
+      "mode": "direct",
+      "handler": "./src/handlers"
+    }
+  }
+}
+```
+- Service Wrapper calls handlers directly
+- No HTTP overhead
+- 50% memory savings
+- Single process
+
+### HTTP Mode (Default/External)
+```json
+{
+  "service": {
+    "execution": {
+      "mode": "http",
+      "baseUrl": "${SERVICE_URL:http://localhost:3000}"
+    }
+  }
+}
+```
+- Service Wrapper makes HTTP calls
+- Service runs separately
+- Better for testing
+- Required for external APIs
+
+## Cookbook Integration
+
+Operations map directly to Cookbook workflow steps:
+
+### Cookbook Step
+```json
+{
+  "step_id": "greet_user",
+  "type": "service_call",
+  "service": "hello-service",
+  "operation": "good-day",
+  "input": {
+    "name": "$.user_name"
+  }
+}
+```
+
+### Corresponding Operation
+```json
+{
+  "operations": {
+    "good-day": {
+      "description": "Generate good day greeting",
+      "handler": "handlers.greetings.goodDay",
+      "endpoint": "/api/good-day",
+      "input": {
+        "name": { "type": "string", "required": true }
+      },
+      "output": {
+        "message": "string",
+        "timestamp": "datetime"
+      }
+    }
+  }
+}
+```
+
+## Handler Implementation
+
+### Direct Mode Handler
+```javascript
+// handlers/greetings.js
+exports.goodDay = async (input) => {
+  const { name } = input;
+  return {
+    message: `Good day, ${name}!`,
+    timestamp: new Date().toISOString()
+  };
+};
+```
+
+### HTTP Mode Endpoint
+```javascript
+// src/app.js
+app.post('/api/good-day', async (req, res) => {
+  const { name } = req.body;
+  res.json({
+    message: `Good day, ${name}!`,
+    timestamp: new Date().toISOString()
+  });
+});
+```
+
+## Validation
+
+Input/output validation is automatic based on the schema:
+
+```javascript
+// Service Wrapper validates automatically
+const operation = operations['good-day'];
+validateInput(input, operation.input);  // Throws if invalid
+const result = await executeOperation(operation, input);
+validateOutput(result, operation.output);  // Throws if invalid
+```
+
+## Migration from OpenAPI
+
+### Before (OpenAPI)
+```yaml
+paths:
+  /v1/good-day:
+    post:
+      operationId: createGoodDay
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GreetingRequest'
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GreetingResponse'
+```
+
+### After (Operations Schema)
+```json
+{
+  "operations": {
+    "good-day": {
+      "handler": "handlers.greetings.goodDay",
+      "endpoint": "/api/good-day",
+      "input": {
+        "name": { "type": "string", "required": true }
+      },
+      "output": {
+        "message": "string",
+        "timestamp": "datetime"
+      }
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **Keep operations focused** - One operation = one business action
+2. **Use descriptive names** - Operation names should be self-explanatory
+3. **Document fields** - Add descriptions to complex fields
+4. **Validate strictly** - Mark required fields appropriately
+5. **Handle errors gracefully** - Define error responses in output
+6. **Use environment variables** - For URLs, keys, and configuration
+7. **Test both modes** - Ensure operations work in both direct and HTTP mode
+
+## Service Wrapper Integration
+
+The Service Wrapper automatically:
+- Loads operations.json on startup
+- Routes Cookbook steps to operations
+- Validates input/output
+- Handles execution mode (direct/HTTP)
+- Manages external API calls
+- Provides metrics and logging
+
+## Example Service Structure
+
+```
+hello-service/
+├── conn-config/
+│   ├── config.json        # Service configuration
+│   ├── operations.json    # Operations schema
+│   └── middleware.json    # Middleware config
+├── src/
+│   ├── app.js            # Express app (for HTTP mode)
+│   └── handlers/         # Handler functions (for direct mode)
+│       └── greetings.js
+└── package.json
+```
+
+## Testing Operations
+
+```javascript
+// Test operation directly
+const operations = require('./conn-config/operations.json');
+const handlers = require('./src/handlers');
+
+test('good-day operation', async () => {
+  const input = { name: 'World' };
+  const result = await handlers.greetings.goodDay(input);
+
+  expect(result.message).toBe('Good day, World!');
+  expect(result.timestamp).toBeDefined();
+});
+```
+
+## Future Extensions
+
+The schema is designed to be extensible:
+
+- **WebSocket operations** - Real-time communication
+- **Message queue operations** - Direct MQ publishing
+- **Database operations** - Direct DB queries
+- **File operations** - S3, MinIO uploads
+- **Batch operations** - Bulk processing
+
+Each extension follows the same pattern:
+1. Define operation in operations.json
+2. Specify type in `external` block
+3. Map inputs/outputs
+4. Service Wrapper handles execution