jsgui3-server 0.0.151 → 0.0.155

package/publishers/http-function-publisher.js

@@ -29,7 +29,51 @@ const {
 
 
 
+/**
+ * Function_Publisher — publishes a JavaScript function as an HTTP API endpoint.
+ *
+ * Wraps a plain function (sync or async) so it can be called over HTTP.
+ * Incoming JSON request bodies are parsed and passed as the function's
+ * first argument.  Return values are JSON-serialised back to the client.
+ *
+ * ## Metadata for OpenAPI / Swagger
+ *
+ * When constructed via `server.publish()`, a `meta` object may be
+ * attached to the spec.  The publisher stores this as `this.api_meta`
+ * and the OpenAPI generator reads it to produce Swagger documentation.
+ *
+ * Supported `meta` / shorthand fields:
+ *
+ * | Field          | Type     | Purpose                                  |
+ * |----------------|----------|------------------------------------------|
+ * | `method`       | string   | HTTP method (`'GET'`, `'POST'`, etc.)    |
+ * | `summary`      | string   | One-line summary for Swagger UI          |
+ * | `description`  | string   | Multi-line Markdown description          |
+ * | `tags`         | string[] | Grouping tags in the Swagger UI          |
+ * | `params`       | Object   | Request body schema (simple format)      |
+ * | `returns`      | Object   | Response body schema (simple format)     |
+ * | `deprecated`   | boolean  | Mark endpoint as deprecated              |
+ * | `operationId`  | string   | Custom OpenAPI operation ID              |
+ *
+ * @extends HTTP_Publisher
+ * @see {@link module:openapi} for the spec generator that reads `api_meta`.
+ */
 class Function_Publisher extends HTTP_Publisher {
+    /**
+     * Create a new Function_Publisher.
+     *
+     * @param {Function|Object} spec - Either a bare function or an options object.
+     * @param {Function}  spec.fn          - The function to publish.
+     * @param {string}    [spec.name]      - Endpoint name (used in route).
+     * @param {Object}    [spec.schema]    - Schema for introspection.
+     * @param {Object}    [spec.meta]      - API metadata for OpenAPI generation.
+     * @param {string}    [spec.summary]   - Shorthand for `meta.summary`.
+     * @param {string}    [spec.description] - Shorthand for `meta.description`.
+     * @param {string[]}  [spec.tags]      - Shorthand for `meta.tags`.
+     * @param {Object}    [spec.params]    - Shorthand for `meta.params`.
+     * @param {Object}    [spec.returns]   - Shorthand for `meta.returns`.
+     * @param {string}    [spec.method]    - Shorthand for `meta.method`.
+     */
     constructor(spec) {
         super(spec);
         //let fn = this.fn = spec;
@@ -46,6 +90,29 @@ class Function_Publisher extends HTTP_Publisher {
             } else {
                 this.schema = {};
             }
+
+            // ── Extended API metadata for OpenAPI / Swagger generation ──
+            //
+            // Metadata can be supplied in two ways:
+            //   1. Nested under `spec.meta` (from server.publish())
+            //   2. As top-level shorthand fields on the spec itself
+            //
+            // Both are merged into `this.api_meta`, with `spec.meta`
+            // taking precedence over shorthand fields.
+            //
+            // The OpenAPI generator (openapi.js) reads `this.api_meta`
+            // to produce requestBody, responses, tags, summary, etc.
+            this.api_meta = {};
+            if (spec.meta && typeof spec.meta === 'object') {
+                this.api_meta = { ...spec.meta };
+            }
+            // Merge top-level shorthand fields (lower precedence).
+            if (spec.summary) this.api_meta.summary = this.api_meta.summary || spec.summary;
+            if (spec.description) this.api_meta.description = this.api_meta.description || spec.description;
+            if (spec.tags) this.api_meta.tags = this.api_meta.tags || spec.tags;
+            if (spec.params) this.api_meta.params = this.api_meta.params || spec.params;
+            if (spec.returns) this.api_meta.returns = this.api_meta.returns || spec.returns;
+            if (spec.method) this.api_meta.method = this.api_meta.method || spec.method;
         }
         this.type = 'function';
         //let fn = spec;
@@ -54,33 +121,18 @@ class Function_Publisher extends HTTP_Publisher {
         // But will need to route to the function publisher.
 
         this.handle_http = (req, res) => {
-            // need to handle observable http request.
-            // Begin sending to that connection...
-            // Following SSE would be nice.
-
-            // Should check to see if it supports compression.
-            //   Compression function middleware could work fine here.
-
-            // Will need to call the function with params.
-            //  Read params from content body?
-
-            const {method, headers} = req;
-
-            //console.log('Function Publisher handle_http method', method);
-            //console.log('headers', headers);
-
-            // Need to get the incoming parameters.
-            // Need to use formidable or whatever else...?
-
-            // Need to wait for the whole of the request to complete.
-            //  Don't think it will be multipart forms.
+            const { method, headers } = req;
+
+            // ── Parse query string from the URL ──
+            let query_params = {};
+            try {
+                const parsed_url = new URL(req.url, `http://${headers.host || 'localhost'}`);
+                query_params = Object.fromEntries(parsed_url.searchParams.entries());
+            } catch (e) {
+                // Fallback: no query params if URL parsing fails.
+            }
 
-            const content_length = headers['content-length'];
             const content_type = headers['content-type'];
-            // could be the mime type and the charset.
-
-            //  then need to wait for the whole thing.
-            //   think the req is a Readable_Stream.
 
             const chunks = [];
 
@@ -90,77 +142,76 @@ class Function_Publisher extends HTTP_Publisher {
 
             req.on('end', () => {
                 const buf_input = Buffer.concat(chunks);
-                //console.log('buf_input', buf_input);
-
-                // then interpret it according to the content_type
-                let obj_input;
-                //console.log('content_type', content_type);
-                if (!content_type) {
-                    console.log('buf_input.length', buf_input.length);
-                    if (buf_input.length === 0) {
-
-                    } else {
-                        console.trace();
-                        throw 'NYI';
-                    }
-                } else {
-                    if (content_type.startsWith('text/plain')) {
-                    obj_input = buf_input.toString();
-
-                } else {
 
-                    if (content_type === 'application/json') {
+                // ── Parse request body ──
+                let body_input = null;
+                if (buf_input.length > 0) {
+                    if (!content_type) {
+                        // No content-type but has body — try JSON parse.
+                        try {
+                            body_input = JSON.parse(buf_input.toString());
+                        } catch (e) {
+                            body_input = buf_input.toString();
+                        }
+                    } else if (content_type.startsWith('text/plain')) {
+                        body_input = buf_input.toString();
+                    } else if (content_type === 'application/json' || content_type.startsWith('application/json')) {
                         const inputStr = buf_input.toString();
-                        if (inputStr.trim() === '') {
-                            obj_input = null;
-                        } else {
-                            obj_input = JSON.parse(inputStr);
+                        if (inputStr.trim() !== '') {
+                            body_input = JSON.parse(inputStr);
                         }
                     } else {
-                        console.trace();
-                        throw 'NYI';
+                        // Unknown content type — try JSON, fall back to string.
+                        try {
+                            body_input = JSON.parse(buf_input.toString());
+                        } catch (e) {
+                            body_input = buf_input.toString();
+                        }
                     }
-                    // decode / parse JSON.
                 }
-                }
-
-                
 
+                // ── Merge inputs: path params < query params < body ──
+                // Priority (highest wins): body > query > path params
+                const path_params = (req.params && typeof req.params === 'object') ? req.params : {};
+                const has_query = Object.keys(query_params).length > 0;
+                const has_path = Object.keys(path_params).length > 0;
+                const has_body = body_input !== null && body_input !== undefined;
+
+                let merged_input;
+                if (has_body && typeof body_input === 'object' && !Array.isArray(body_input)) {
+                    // Body is an object — merge with path + query params.
+                    merged_input = { ...path_params, ...query_params, ...body_input };
+                } else if (has_body) {
+                    // Body is a string or array — use as-is if no path/query params.
+                    if (has_path || has_query) {
+                        merged_input = { ...path_params, ...query_params, _body: body_input };
+                    } else {
+                        merged_input = body_input;
+                    }
+                } else if (has_query || has_path) {
+                    // No body — use path + query params as input.
+                    merged_input = { ...path_params, ...query_params };
+                } else {
+                    // Nothing at all.
+                    merged_input = undefined;
+                }
 
                 const output_all = (call_res) => {
-                    // But not a buffer, string???
-                    // res is response.
                     const tcr = tf(call_res);
-
-                    console.log('tcr', tcr);
-
                     res.writeHead(200, {
-                        'Content-Type': 'application/json'//,
-                        //'Transfer-Encoding': 'chunked',
-                        //'Trailer': 'Content-MD5'
+                        'Content-Type': 'application/json'
                     });
                     res.end(JSON.stringify(call_res));
                 }
 
-
-                // And the function to call may be async.
-                //  Can test to see if we get a promise (or observable) back from it.
-
                 try {
-                    const fn_res = fn(obj_input);
+                    const fn_res = fn(merged_input);
                     const tfr = tf(fn_res);
-                    //console.log('fn_res', fn_res);
-
-                    //
 
                     if (tfr === 'p') {
                         // promise
-                        console.log('need to await promise resolution');
-
                         fn_res.then(call_res => {
-                            console.log('fn_res then happened, call_res', call_res);
                             output_all(call_res);
-
                         }, err => {
                             console.error('Function execution error:', err);
                             if (!res.headersSent) {
@@ -170,36 +221,22 @@ class Function_Publisher extends HTTP_Publisher {
                                 res.end(JSON.stringify({ error: err.message }));
                             }
                         });
-
-
                     } else if (tfr === 's') {
-                        // Just write it as a string for the moment I think?
-                        //   Or always encode as JSON?
-
-                        // text/plain;charset=UTF-8
-
                         res.writeHead(200, {
-                            'Content-Type': 'text/plain;charset=UTF-8'//,
-                            //'Transfer-Encoding': 'chunked',
-                            //'Trailer': 'Content-MD5'
+                            'Content-Type': 'text/plain;charset=UTF-8'
                         });
                         res.end(fn_res);
-
-
                     } else if (tfr === 'o' || tfr === 'a') {
-                        // Just write it as a string for the moment I think?
-                        //   Or always encode as JSON?
-
-                        // text/plain;charset=UTF-8
-
                         res.writeHead(200, {
-                            'Content-Type': 'application/json'//,
-                            //'Transfer-Encoding': 'chunked',
-                            //'Trailer': 'Content-MD5'
+                            'Content-Type': 'application/json'
                         });
                         res.end(JSON.stringify(fn_res));
-
-
+                    } else if (tfr === 'u' || tfr === 'n') {
+                        // undefined or null return — send empty 200
+                        res.writeHead(200, {
+                            'Content-Type': 'application/json'
+                        });
+                        res.end('null');
                     } else {
                         console.log('tfr', tfr);
                         console.trace();
@@ -214,43 +251,15 @@ class Function_Publisher extends HTTP_Publisher {
                         res.end(JSON.stringify({ error: err.message }));
                     }
                 }
-
-
-
-
-
-                // turn it to string?
-                //  check its mime type?
-
-                // however, likely we should have been told its application/json if that's the case.
-                //  likely will be the case for function calls.
-
-                //  the jsgui http post call....
-                //   should set the mime type where possible to intelligently do so.
-
-
-
-
-                // may get some polymorphism out of the mime types.
-                //  text/plain;charset=UTF-8
-                //    turn it to a string.
-
-
-
             });
 
 
 
 
-
-
-
-
-
             /*
-
+        
             
-
+        
             
             */
 

package/publishers/http-webpage-publisher.js

@@ -102,7 +102,8 @@ class HTTP_Webpage_Publisher extends HTTP_Webpageorsite_Publisher {
         const render_webpage = async () => {
 
             const { webpage } = this;
-            const Ctrl = webpage.content;
+            // Use ctrl (modern Webpage API) with fallback to content (legacy)
+            const Ctrl = webpage.ctrl || webpage.content;
 
             // In business activating it with the page context.
 
@@ -194,21 +195,98 @@ class HTTP_Webpage_Publisher extends HTTP_Webpageorsite_Publisher {
     }
 
 
-    handle_http(req, res) {
-        console.log('HTTP_Webpage_Publisher handle_http');
-        console.log('req.url', req.url);
-
+    async handle_http(req, res) {
         const { webpage } = this;
+        // Use ctrl (modern Webpage API) with fallback to content (legacy)
+        const Ctrl = webpage.ctrl || webpage.content;
 
-        const Ctrl = webpage.content;
-        const ctrl = new Ctrl();
+        if (typeof Ctrl !== 'function') {
+            res.writeHead(500, { 'Content-Type': 'text/plain' });
+            res.end('Admin page control is not available');
+            return;
+        }
 
-        res.writeHead(200, {
-            'Content-Type': 'text/html'
-        });
+        try {
+            const static_page_context = new Server_Static_Page_Context();
+
+            const ctrl = new Ctrl({
+                context: static_page_context
+            });
 
-        res.end(ctrl.all_html_render());
+            let html;
 
+            if (ctrl.head && ctrl.body) {
+                // Control is a full document (has head/body) — inject CSS/JS directly
+                const ctrl_css_link = new jsgui_client.controls.link({
+                    context: static_page_context
+                });
+                ctrl_css_link.dom.attributes.rel = 'stylesheet';
+                ctrl_css_link.dom.attributes.href = '/css/css.css';
+                ctrl.head.add(ctrl_css_link);
+
+                const ctrl_js_script_link = new jsgui_client.controls.script({
+                    context: static_page_context
+                });
+                ctrl_js_script_link.dom.attributes.src = '/js/js.js';
+                ctrl.body.add(ctrl_js_script_link);
+
+                ctrl.active();
+                html = await ctrl.all_html_render();
+            } else {
+                // Control is not a document — wrap it in Active_HTML_Document
+                const Active_HTML_Document = require('../controls/Active_HTML_Document');
+
+                const doc = new Active_HTML_Document({
+                    context: static_page_context
+                });
+
+                if (webpage.title) {
+                    // Set the page title if available
+                    const title = typeof webpage.get_title === 'function'
+                        ? webpage.get_title() : webpage.title;
+                    if (title && doc.head) {
+                        const title_ctrl = new jsgui_client.controls.ctrl({
+                            context: static_page_context,
+                            'dom.tagName': 'title'
+                        });
+                        title_ctrl.dom.text = title;
+                        doc.head.add(title_ctrl);
+                    }
+                }
+
+                // Add CSS link to head
+                const ctrl_css_link = new jsgui_client.controls.link({
+                    context: static_page_context
+                });
+                ctrl_css_link.dom.attributes.rel = 'stylesheet';
+                ctrl_css_link.dom.attributes.href = '/css/css.css';
+                doc.head.add(ctrl_css_link);
+
+                // Add the control to body
+                doc.body.add(ctrl);
+
+                // Add JS script link to body
+                const ctrl_js_script_link = new jsgui_client.controls.script({
+                    context: static_page_context
+                });
+                ctrl_js_script_link.dom.attributes.src = '/js/js.js';
+                doc.body.add(ctrl_js_script_link);
+
+                doc.active();
+                html = await doc.all_html_render();
+            }
+
+            res.writeHead(200, {
+                'Content-Type': 'text/html; charset=utf-8'
+            });
+            res.end(html);
+        } catch (e) {
+            console.error('[HTTP_Webpage_Publisher] handle_http render error:', e);
+            if (!res.headersSent) {
+                res.writeHead(500, { 'Content-Type': 'text/plain' });
+                res.end('Internal Server Error: Failed to render page');
+            }
+        }
     }
 }
 

package/publishers/query-publisher.js

@@ -0,0 +1,116 @@
+/**
+ * Query_Publisher — a Function_Publisher pre-configured for the
+ * standard data-view query protocol.
+ *
+ * Wraps a query function (typically from a Query_Resource) into an
+ * HTTP endpoint that:
+ * - accepts JSON params: { page, page_size, sort, filters }
+ * - returns JSON:        { rows, total_count, page, page_size }
+ * - handles errors uniformly
+ *
+ * @example
+ *   const Query_Publisher = require('jsgui3-server/publishers/query-publisher');
+ *
+ *   // With a raw function:
+ *   const pub = new Query_Publisher({
+ *       name: 'users',
+ *       query_fn: async (params) => {
+ *           const rows = await db.all('SELECT ...');
+ *           return { rows, total_count: 100 };
+ *       }
+ *   });
+ *
+ *   // With a Query_Resource (preferred):
+ *   const pub2 = Query_Publisher.from_resource(my_query_resource);
+ */
+
+const Function_Publisher = require('./http-function-publisher');
+
+class Query_Publisher extends Function_Publisher {
+    /**
+     * @param {Object}   spec
+     * @param {string}   spec.name              - Endpoint name (used in route).
+     * @param {Function} spec.query_fn          - async (params) => {rows, total_count}
+     * @param {Object}   [spec.schema]          - Column definitions for introspection.
+     * @param {number}   [spec.default_page_size=25]
+     * @param {number}   [spec.max_page_size=1000]
+     */
+    constructor(spec = {}) {
+        const query_fn = spec.query_fn;
+        if (typeof query_fn !== 'function') {
+            throw new Error('Query_Publisher requires a query_fn(params) function.');
+        }
+
+        const default_page_size = spec.default_page_size || 25;
+        const max_page_size = spec.max_page_size || 1000;
+
+        // Wrap the query_fn in a handler that normalizes input/output.
+        const handler_fn = async (input) => {
+            const params = input || {};
+
+            // Normalize params
+            const page = Math.max(1, Math.floor(Number(params.page) || 1));
+            const raw_page_size = Number(params.page_size);
+            const page_size = Number.isFinite(raw_page_size) && raw_page_size > 0
+                ? Math.min(Math.floor(raw_page_size), max_page_size)
+                : default_page_size;
+
+            let sort = null;
+            if (params.sort && typeof params.sort === 'object' && params.sort.key) {
+                sort = {
+                    key: String(params.sort.key),
+                    dir: String(params.sort.dir || 'asc').toLowerCase() === 'desc' ? 'desc' : 'asc'
+                };
+            }
+
+            let filters = null;
+            if (params.filters && typeof params.filters === 'object') {
+                filters = params.filters;
+            }
+
+            const normalized = { page, page_size, sort, filters };
+            const result = await query_fn(normalized);
+
+            return {
+                rows: Array.isArray(result.rows) ? result.rows : [],
+                total_count: Number.isFinite(result.total_count) ? result.total_count : 0,
+                page,
+                page_size
+            };
+        };
+
+        super({
+            fn: handler_fn,
+            name: spec.name,
+            schema: spec.schema || {}
+        });
+
+        this.type = 'query';
+        this.query_schema = spec.schema || {};
+        this.default_page_size = default_page_size;
+        this.max_page_size = max_page_size;
+    }
+
+    /**
+     * Create a Query_Publisher from a Query_Resource instance.
+     *
+     * @param {Query_Resource} resource - A Query_Resource with a query() method.
+     * @param {Object} [options]        - Additional options (name override, schema override).
+     * @returns {Query_Publisher}
+     */
+    static from_resource(resource, options = {}) {
+        if (!resource || typeof resource.query !== 'function') {
+            throw new Error('from_resource requires a resource with a query() method.');
+        }
+
+        return new Query_Publisher({
+            name: options.name || resource.name,
+            query_fn: (params) => resource.query(params),
+            schema: options.schema || resource.schema,
+            default_page_size: options.default_page_size || resource.default_page_size,
+            max_page_size: options.max_page_size
+        });
+    }
+}
+
+module.exports = Query_Publisher;