divhunt 2.0.0

package/addons/core/commands/README.md

@@ -0,0 +1,294 @@
+## Built with the Divhunt Framework – non-commercial use only. For commercial use, contact dejan@divhunt.com.
+
+# Commands Addon
+
+The Commands addon provides a structured way to define and manage API endpoints with automatic validation, routing, and response formatting.
+
+## Basic Usage
+
+### Creating a Command
+
+```javascript
+import commands from '#commands/load.js';
+
+commands.Item({
+    id: 'users:create',
+    method: 'POST',
+    endpoint: '/api/users',
+    type: 'JSON',
+    description: 'Create a new user',
+    in: {
+        name: ['string', null, true],
+        email: ['string', null, true],
+        age: ['number']
+    },
+    out: {
+        user: {
+            type: 'object',
+            config: {
+                id: ['string'],
+                name: ['string'],
+                email: ['string']
+            }
+        }
+    },
+    callback: async function(properties, resolve) {
+        // Your logic here
+        const user = createUser(properties);
+        resolve({user});
+    }
+});
+```
+
+## Command Properties
+
+### Required Fields
+
+- **id** - Unique identifier for the command
+- **callback** - Function that executes the command logic
+
+### Optional Fields
+
+- **method** - HTTP method (`GET`, `POST`, `PUT`, `DELETE`). Default: `GET`
+- **endpoint** - URL pattern (supports route parameters with `:param`)
+- **type** - Response type (`JSON`, `HTML`, `CSS`, `JSS`). Default: `JSON`
+- **description** - Human-readable description
+- **in** - Input validation schema
+- **out** - Output validation schema
+
+## Route Parameters
+
+Use `:parameter` syntax in endpoints to capture URL segments:
+
+```javascript
+commands.Item({
+    id: 'users:get:one',
+    method: 'GET',
+    endpoint: '/api/users/:id',
+    in: {
+        id: ['string', null, true]
+    },
+    callback: async function(properties, resolve) {
+        // properties.id contains the URL parameter
+        const user = await findUser(properties.id);
+        resolve({user});
+    }
+});
+```
+
+## Input Validation
+
+Define input schemas to automatically validate request data:
+
+```javascript
+// Simple validation
+in: {
+    name: ['string', null, true], // required string
+    age: ['number', 18],          // optional number, default 18
+    active: ['boolean', true]     // optional boolean, default true
+}
+
+// Complex validation
+in: {
+    user: {
+        type: 'object',
+        config: {
+            profile: {
+                type: 'object',
+                config: {
+                    name: ['string', null, true],
+                    contacts: {
+                        type: 'array',
+                        each: {
+                            type: 'object',
+                            config: {
+                                type: ['string'],
+                                value: ['string']
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+// Using predefined schemas
+in: 'user --skip=id --skip=created_at'
+```
+
+## Output Validation
+
+Define output schemas to validate and format responses:
+
+```javascript
+out: {
+    users: {
+        type: 'array',
+        each: {
+            type: 'object',
+            config: {
+                id: ['string'],
+                name: ['string'],
+                email: ['string']
+            }
+        }
+    },
+    total: ['number', null, true],
+    page: ['number', null, true]
+}
+```
+
+## Callback Function
+
+The callback receives two parameters:
+
+```javascript
+callback: async function(properties, resolve) {
+    // properties - validated input data
+    // resolve(data, message, code) - response function
+    
+    try {
+        const result = await doSomething(properties);
+        resolve(result); // Success with default message and 200 code
+    } catch (error) {
+        resolve(null, 'Error occurred', 500);
+    }
+}
+```
+
+### Resolve Function
+
+```javascript
+resolve(data, message, code)
+```
+
+- **data** - Response data (will be validated against `out` schema)
+- **message** - Response message (optional, has default)
+- **code** - HTTP status code (optional, default: 200)
+
+## Finding Commands
+
+### Find by Method and Path
+
+```javascript
+const command = commands.Fn('find', 'GET', '/api/users/123');
+```
+
+## Running Commands
+
+```javascript
+const command = commands.ItemGet('users:create');
+const result = await command.Fn('run', inputData, context);
+
+// Returns:
+// {
+//     data: {...},      // Validated output
+//     message: "...",   // Success/error message  
+//     code: 200         // HTTP status code
+// }
+```
+
+## Response Types
+
+### JSON (Default)
+
+```javascript
+type: 'JSON' // Returns application/json
+```
+
+### HTML
+
+```javascript
+type: 'HTML' // Returns text/html
+```
+
+### CSS
+
+```javascript
+type: 'CSS' // Returns text/css  
+```
+
+### JavaScript
+
+```javascript
+type: 'JSS' // Returns application/javascript
+```
+
+## Built-in Commands
+
+The addon includes two built-in commands:
+
+### List All Commands
+
+```
+GET /api/commands
+```
+
+Returns all registered commands with their metadata.
+
+### Get Single Command
+
+```
+GET /api/commands/:id
+```
+
+Returns details for a specific command.
+
+## Data Type Hints
+
+Use type hints in property names for automatic conversion:
+
+```javascript
+// URL: /api/users?age:number=25&active:boolean=true&tags:array=tag1,tag2
+
+// Converts to:
+// {
+//     age: 25,           // number
+//     active: true,      // boolean  
+//     tags: ['tag1', 'tag2'] // array
+// }
+```
+
+Available hints:
+- `:number` - Convert to number
+- `:string` - Convert to string
+- `:boolean` - Convert to boolean (`true`, `1`, `false`, `0`)
+- `:array` - Convert to array (comma-separated or JSON)
+- `:object` - Convert to object (JSON)
+
+## Error Handling
+
+Commands automatically handle validation errors and return appropriate error responses:
+
+```javascript
+// Input validation error
+{
+    data: "Error message",
+    message: "Request contains invalid parameters.",
+    code: 400
+}
+
+// Command not found
+{
+    data: {},
+    message: "Command does not exist.",
+    code: 404
+}
+
+// Server error
+{
+    data: {},
+    message: "Command could not be completed.",
+    code: 500
+}
+```
+
+## Best Practices
+
+1. **Use descriptive IDs** - Follow pattern `resource:action` or `resource:action:modifier`
+2. **Validate inputs** - Always define `in` schema for data integrity
+3. **Handle errors gracefully** - Use try/catch and appropriate error codes
+4. **Use route parameters** - Prefer `/users/:id` over query parameters for resources
+5. **Document commands** - Add meaningful descriptions
+6. **Consistent responses** - Use standard response format across commands# commands

package/addons/core/commands/back/addon.js

@@ -0,0 +1,31 @@
+// © 2025 Divhunt GmbH — Licensed under the Divhunt Framework License. See LICENSE for terms.
+
+import divhunt from '#framework/load.js';
+
+const commands = divhunt.Addon('commands', (addon) =>
+{
+    addon.Field('id', ['string|number']);
+    addon.Field('type', ['string', 'JSON']);
+    addon.Field('description', ['string']);
+    addon.Field('in', ['object|string']);
+    addon.Field('out', ['object|string']);
+    addon.Field('exposed', ['boolean', false]);
+    addon.Field('callback', ['function']);
+    
+    addon.Field('method', ['string', 'GET'], null, (value) =>
+    {
+        return ['GET', 'POST', 'PUT', 'DELETE'].includes(value) ? value : 'GET';
+    });
+
+    addon.Field('endpoint', ['string'], null, (value) =>
+    {
+        if(!value)
+        {
+            return null;
+        }
+
+        return '/' + value.replace(/^\/+/, '').replace(/\/+/g, '/').toLowerCase();
+    });
+});
+
+export default commands;

package/addons/core/commands/back/functions/find.js

@@ -0,0 +1,54 @@
+// © 2025 Divhunt GmbH — Licensed under the Divhunt Framework License. See LICENSE for terms.
+
+import commands from '../addon.js';
+
+commands.Fn('find', function(method, pathname)
+{
+    const normalizedPathname = pathname.toLowerCase();
+    
+    const items = Object.values(this.Items());
+    
+    for (const item of items) 
+    {
+        if (item.Get('method') !== method) 
+        {
+            continue;
+        }
+        
+        const endpoint = item.Get('endpoint');
+        
+        if (endpoint === normalizedPathname) 
+        {
+            return item;
+        }
+        
+        if ((endpoint + '').includes(':')) 
+        {
+            const endpointParts = endpoint.split('/');
+            const pathParts = normalizedPathname.split('/');
+            
+            if (endpointParts.length !== pathParts.length) 
+            {
+                continue;
+            }
+            
+            let matches = true;
+            
+            for (let i = 0; i < endpointParts.length; i++) 
+            {
+                if (!endpointParts[i].startsWith(':') && endpointParts[i] !== pathParts[i]) 
+                {
+                    matches = false;
+                    break;
+                }
+            }
+            
+            if (matches) 
+            {
+                return item;
+            }
+        }
+    }
+
+    return items.find((item) => item.Get('endpoint') === '/*');
+});

package/addons/core/commands/back/functions/grpc/client.js

@@ -0,0 +1,155 @@
+import commands from '../../addon.js';
+
+commands.Fn('grpc.client', async function(host, port, metadata = {}, prefix = 'remote', bidirectional = false, callbacks = {})
+{
+    const grpcClients = (await import('#clients/grpc/load.js')).default;
+    const store = new Set();
+    const retry = { tries: 0, retries: 20, delay: 15000, timeout: null };
+
+    const connect = () =>
+    {
+        if(retry.timeout)
+        {
+            clearTimeout(retry.timeout);
+            retry.timeout = null;
+        }
+
+        const client = grpcClients.Item(
+        {
+            host,
+            port,
+            metadata,
+            onConnect: function(client)
+            {
+                retry.tries = 0;
+                callbacks['onConnect'] && callbacks['onConnect'](client);
+                this.Fn('stream');
+            },
+
+            onStream: async function(stream)
+            {
+                callbacks['onStream'] && callbacks['onStream'](stream);
+
+                const result = await stream.request('commands:get:many');
+
+                if(result.code !== 200)
+                {
+                    return stream.cancel();
+                }
+
+                const list = result.data.commands;
+
+                list.forEach((command) =>
+                {
+                    const id = prefix + ':' + command.id;
+
+                    commands.Item(
+                    {
+                        id,
+                        in: command.data.in,
+                        out: command.data.out,
+                        callback: async (properties, resolve) =>
+                        {
+                            const result = await stream.request(command.id, properties, (chunk) =>
+                            {
+                                callbacks['onStreamChunk'] && callbacks['onStreamChunk'](stream, chunk);
+                                resolve(chunk.data, chunk.message, chunk.code, chunk.end);
+                            });
+
+                            resolve(result.data, result.message, result.code, result.end);
+                        }
+                    });
+
+                    store.add(id);
+                });
+
+                callbacks['onCommands'] && callbacks['onCommands'](stream, store);
+            },
+
+            onStreamData: async function(stream, payload)
+            {
+                if(!bidirectional)
+                {
+                    return stream.respond(null, 'Client does not support a bidirectional streaming.', 404, true, payload.id);
+                }
+
+                if(payload.type === 'request')
+                {
+                    try
+                    {
+                        const command = commands.ItemGet(payload.name);
+
+                        if(!command)
+                        {
+                            throw new Error('Command does not exist.');
+                        }
+
+                        if(store.has(payload.name))
+                        {
+                            throw new Error('Cannot execute remote commands recursively.');
+                        }
+
+                        if(payload.name.startsWith(prefix + ':'))
+                        {
+                            throw new Error('Cannot execute ' + prefix + ' commands recursively.');
+                        }
+
+                        const result = await command.Fn('run', payload.data, (chunk) =>
+                        {
+                            callbacks['onStreamChunk'] && callbacks['onStreamChunk'](stream, chunk);
+                            stream.respond(chunk.data, chunk.message, chunk.code, chunk.end, payload.id);
+                        });
+
+                        callbacks['onStreamRespond'] && callbacks['onStreamRespond'](stream, payload, result.data, result.message, result.code, payload.id);
+                        stream.respond(result.data, result.message, result.code, result.end, payload.id);
+                    }
+                    catch(error)
+                    {
+                        callbacks['onStreamRespond'] && callbacks['onStreamRespond'](stream, payload, null, error.message, 500, payload.id);
+                        stream.respond(null, error.message, 500, true, payload.id);
+                    }
+                }
+            },
+
+            onStreamEnd: function(stream)
+            {
+                callbacks['onStreamEnd'] && callbacks['onStreamEnd'](stream);
+
+                store.forEach(id =>
+                {
+                    commands.ItemRemove(id);
+                });
+                
+                store.clear();
+
+                if(retry.tries < retry.retries)
+                {
+                    retry.tries++;
+                    retry.timeout = setTimeout(() => connect(), retry.delay);
+                }
+            },
+
+            onStreamError: function(stream, message)
+            {
+                callbacks['onStreamError'] && callbacks['onStreamError'](stream, message);
+            },
+            
+            onError: function(message)
+            {
+                callbacks['onError'] && callbacks['onError'](message);
+
+                if(retry.tries < retry.retries)
+                {
+                    client.Remove();
+
+                    retry.tries++;
+                    retry.timeout = setTimeout(() => connect(), retry.delay);
+                }
+            }
+        });
+
+        return client;
+    };
+
+    return connect();
+});

package/addons/core/commands/back/functions/grpc/server.js

@@ -0,0 +1,71 @@
+// © 2025 Divhunt GmbH — Licensed under the Divhunt Framework License. See LICENSE for terms.
+
+import commands from '../../addon.js';
+
+commands.Fn('grpc.server', async function(port = 50000, callbacks = {})
+{
+    const grpcServers = (await import('#servers/grpc/load.js')).default;
+    const server = grpcServers.Item({
+        port: port,
+        onStart: function()
+        {
+            callbacks['onStart'] && callbacks['onStart']();
+        },
+        onStreamConnect: (stream) => 
+        {
+            callbacks['onStreamConnect'] && callbacks['onStreamConnect'](stream);
+        },
+        onStreamData: async (stream, payload) => 
+        {
+            callbacks['onStreamData'] && callbacks['onStreamData'](stream, payload);
+
+            if(payload.type !== 'request')
+            {
+                return;
+            }
+
+            const command = commands.ItemGet(payload.name);
+
+            try
+            {
+                if(!command)
+                {
+                    throw new Error('Command does not exist.');
+                }
+
+                if(!command.Get('exposed'))
+                {
+                    throw new Error('Command is not exposed.');
+                }
+
+                const result = await command.Fn('run', payload.data, (chunk) =>
+                {
+                    callbacks['onStreamChunk'] && callbacks['onStreamChunk'](stream, chunk);
+                    stream.respond(chunk.data, chunk.message, chunk.code, chunk.end, payload.id);
+                });
+
+                callbacks['onStreamRespond'] && callbacks['onStreamRespond'](stream, result);
+                stream.respond(result.data, result.message, result.code, result.end, payload.id);
+            }
+            catch(error)
+            {
+                callbacks['onStreamRespond'] && callbacks['onStreamRespond'](stream, { data: null, message: error.message, code: 500 });
+                return stream.respond(null, error.message, 500, true, payload.id);
+            }
+        },
+        onError: (message) => 
+        {
+            callbacks['onError'] && callbacks['onError'](message);
+        },
+        onStreamError: function(stream)
+        {
+            callbacks['onStreamError'] && callbacks['onStreamError'](stream);
+        },
+        onStreamEnd: function(stream)
+        {
+            callbacks['onStreamEnd'] && callbacks['onStreamEnd'](stream);
+        }
+    });
+    
+    return server;
+});

package/addons/core/commands/back/functions/http/server.js

@@ -0,0 +1,91 @@
+// © 2025 Divhunt GmbH — Licensed under the Divhunt Framework License. See LICENSE for terms.
+
+import divhunt from '#framework/load.js';
+import commands from '../../addon.js';
+
+commands.Fn('http.server', async function(port = 3000, callbacks = {})
+{
+    const serversHTTP = (await import('#servers/http/load.js')).default;
+
+    return serversHTTP.Item({
+        port,
+        onStart: (server) =>
+        {
+            callbacks['onStart'] && callbacks['onStart'](server);
+        },
+        onRequest: async (http) =>
+        {
+            const onRequestResult = callbacks['onRequest'] && await callbacks['onRequest'](http);
+
+            if(onRequestResult === false || http.prevent)
+            {
+                callbacks['onResponse'] && callbacks['onResponse'](http);
+                return;
+            }
+
+            const command = commands.Fn('find', http.request.method, http.url.pathname);
+
+            if(!command || !command.Get('exposed'))
+            {
+                http.response.code = 404;
+                http.response.message = 'Command not found.';
+
+                callbacks['onResponse'] && callbacks['onResponse'](http);
+                return;
+            }
+
+            // Extract path parameters from URL
+            const endpoint = command.Get('endpoint');
+            const params = divhunt.RouteParams(endpoint, decodeURIComponent(http.url.pathname));
+
+            if (params)
+            {
+                Object.assign(http.data, params);
+            }
+
+            const type = http.types[command.Get('type')] || http.types.JSON;
+
+            if(http.data.streaming)
+            {
+                http.data.streaming = 1;
+                http.prevent = true;
+                http.raw.writeHead(200, {
+                    'Content-Type': type.contentType,
+                    'Transfer-Encoding': 'chunked'
+                });
+            }
+
+            const response = await command.Fn('run', http.data, (chunk) =>
+            {
+                if(http.data.streaming)
+                {
+                    http.data.streaming++;
+                    http.raw.write(type.formatter(chunk.data) + '\n');
+                }
+
+                callbacks['onChunk'] && callbacks['onChunk'](http, chunk);
+            }, {http});
+
+            if(http.data.streaming)
+            {
+                if(http.data.streaming === 1)
+                {
+                    http.raw.write(type.formatter(response.data) + '\n');
+                }
+
+                http.raw.end();
+            }
+
+            http.response.type = command.Get('type');
+            http.response.data = response.data;
+            http.response.message = response.message;
+            http.response.code = response.code;
+
+            callbacks['onResponse'] && callbacks['onResponse'](http);
+        },
+        onError: (error) =>
+        {
+            callbacks['onError'] && callbacks['onError'](error);
+        }
+    });
+});