@naanlang/naan 1.5.0 → 1.7.0

package/frameworks/browser/worker.nlg

@@ -0,0 +1,295 @@
+/*
+ * worker.nlg
+ * Naanlib/frameworks/browser
+ *
+ * Manage web-based NaaN instances.
+ *
+ * NaaN instances are managed by a top/bottom pair of of objects. InBot (INstance BOTtom) objects
+ * reside in the same JavaScript environment (node/browser) as their worker and communicate with the
+ * appropriate env_xxx.js adapter for NaaN in that environment.
+ *
+ * Zero or more InTop objects connect to each InBot object via the IMP network, providing remote
+ * evaluation and terminal access services. Each InTop supports only one terminal simultaneously, but
+ * they can be attached and detached at any time.
+ *
+ * column positioning:                          //                          //                      !
+ *
+ * Copyright (c) 2026 by Richard C. Zulch
+ *
+ */
+
+
+/*
+ * InBot
+ *
+ * Create a remote interface for a single execution instance, returning the object. This provides
+ * instance access to zero or more InTops via IMP connections. The tops subscribe to receive
+ * notifications/responses. This runs in the main thread and communicates with the worker via the
+ * standard JS messaging interface.
+ *
+ * Options:
+ *  {
+ *      name:       <string>                    // target name, e.g. "Play"
+ *      type:       <string>                    // target category, e.g. "Local"
+ *      startup:    <dictionary>                // startup options
+ *      workerID:   <string>                    // initialize worker with this
+ *      topOriginID:  <string>                  // so top can route to us through IMP
+ *  }
+ *
+ */
+
+closure InBot(worker, options, local inbot)
+{
+    global(App)
+    inbot = new(object, this)
+    inbot.topsubs = []
+    options = merge({
+        type: "Local"
+    }, options)
+    inbot.workerID = options.workerID
+    inbot.worker = worker
+
+    inbot.instanceID = UUID()
+    inbot.sender = App.imp.register(inbot, {
+        name: options.name
+        type: options.type
+        instanceID: inbot.instanceID
+        services: ["naan-worker"]
+    })
+
+    // If this InBot is created remotely then we need to send a message from our new instanceID
+    // to the InTop origin so that it can send messages to us. The intermediate gateways save the
+    // route to allow replies.
+    if options.topOriginID && options.topOriginID != App.imp.us.instanceID
+        inbot.sender(options.topOriginID)                                   // create route top->bottom
+
+    // subscribe
+    //
+    // Add an InTop to our subscribers if not already known.
+    //
+    function subscribe(destID) {
+        if !inbot.topsubs.find(function(item) { item == destID }) {
+            inbot.topsubs.push(destID)
+            if inbot.workerDestID
+                inbot.sender(destID, {
+                    id: "workerDestID"
+                    workerDestID: inbot.workerDestID
+                })
+        }
+    }
+
+    // unsubscribe
+    //
+    // Remove an InTop from our subscribers if present.
+    //
+    function unsubscribe(destID) {
+        inbot.topsubs = inbot.topsubs.filter(function(item) { item != destID })
+    }
+
+    // notifyAll
+    //
+    // Send the message to all our subscribers.
+    //
+    inbot.notifyAll = function notifyAll(message, exceptID, local topDestID) {
+        for topDestID in inbot.topsubs
+            if topDestID != exceptID
+                inbot.sender(topDestID, message)
+    }
+
+    // impUnknown
+    //
+    // Received an unknown destination notice from the other side.
+    //
+    inbot.impUnknown = function impUnknown(unknownID, sourceID, gateway) {
+        if inbot.topsubs[unknownID] {                                       // did not have courtesy to unsubscribe!
+            unsubscribe(unknownID)
+            return
+        }
+        if !gateway
+            debuglog("InBot.impUnknownID:", unknownID, "sourceID:", sourceID)
+    }
+
+    // impReceive
+    //
+    // Received a message from InTop.
+    //
+    inbot.impReceive = function impReceive(message, sourceID) {
+        if message.id == "destroy"
+            destroy()                                                       // told to destroy worker
+        else if message.id == "subscribe"
+            subscribe(sourceID)
+        else if message.id == "unsubscribe"
+            unsubscribe(sourceID)
+        else if message.id == "typed"
+            notifyAll(message, sourceID)
+        else {                                                              // relay to worker
+            message.scope = "naan-env-web"
+            inbot.worker.postMessage(message)
+        }
+    }
+
+    // onmessage
+    //
+    // A message was received from the worker.
+    //
+    inbot.worker.addEventListener("message", function(e, local msg) {
+        msg = new(e.data)
+        if msg.scope == "naan-imp-web" {
+            inbot.impconn.dispatch(msg.data)
+            return
+        }
+        if msg.scope != "naan-env-web"
+            return
+        if msg.id == "loaded" {
+            if !inbot.started
+                inbot.worker.postMessage({
+                    scope: "naan-env-web"
+                    id: "start",
+                    state: false                                            // resume state, if we have any
+                    altcmd: options.startup.initcmds
+                    workerID: options.workerID
+                    metadata: {
+                        mainInstanceID: App.imp.us.instanceID
+                        name: options.name
+                        maintext: options.startup.maintext.concat("\n")
+                    }
+                })
+            inbot.started = true
+        }
+        notifyAll(msg)
+    })
+
+    // onerror
+    //
+    // The worker had an error.
+    //
+    inbot.worker.addEventListener("error", function(e) {
+        debuglog("worker error:", e.message, "in", e.filename, "at", e.lineno)
+        notifyAll({
+            id: "error"
+            data: {
+                message: e.message
+                filename: e.filename
+                lineno: e.lineno
+            }
+        })
+        inbot.worker = false
+        destroy()
+    })
+    
+    // destroy
+    //
+    // Ensure the worker is destroyed and notify everyone.
+    //
+    inbot.destroy = function destroy() {
+        if inbot.worker {
+            inbot.worker.terminate()                                        // kill without saving
+            inbot.worker = false
+        }
+        notifyAll({
+            id: "terminated"
+        })
+        inbot.impconn.destroy()
+        inbot.impconn = false
+        App.imp.unregister(inbot.instanceID)
+    }
+
+    // finis
+
+    inbot
+};
+
+
+/*
+ * MewBot
+ *
+ * Create a remote InBot interface for the Main WEb browser thread.
+ *
+ */
+
+closure MewBot(exec, options, local mewbot, inbot_impReceive)
+{
+    global(App)
+    mewbot = InBot(exec, options)
+    mewbot.dispatcher = require("naanlib:frameworks/running/taskexec.nlg").TaskDispatcher()
+    inbot_impReceive = mewbot.impReceive
+
+    // impReceive
+    //
+    // Received a message from InTop.
+    //
+    mewbot.impReceive = function impReceive(message, sourceID) {
+        if message.id == "targetin"
+            mewbot.dispatcher(message.data, function(reply) {
+                mewbot.sender(sourceID, {
+                    id: "targetout",
+                    data: reply
+                })
+            })
+        else
+            inbot_impReceive(message, sourceID)
+    }
+
+    // finis
+
+    mewbot
+}
+
+
+/*
+ * WowBot
+ *
+ * Create a remote InBot interface for WebWorkerNub running in the worker. This forwards remoting
+ * messages to the worker so they can be handled in the correct place.
+ *
+ */
+
+closure WowBot(worker, options, local wowbot)
+{
+    global(App)
+    wowbot = InBot(worker, options)
+
+    App.imp.addEventListener("active", function(event, info) {
+        if info.ourID == wowbot.instanceID {
+            wowbot.workerDestID = info.destID                               // handshake completed
+            wowbot.notifyAll({                                              // send to tops
+                id: "workerDestID"
+                workerDestID: wowbot.workerDestID
+            })
+        }
+    })
+
+    wowbot.impconn = App.imp.responder(function(data) {
+        wowbot.worker.postMessage({                                         // send IMP messages to worker
+            scope: "naan-imp-web"                                           // scoped for WebWorkerNub
+            data: data
+        })
+        list(false, { sent: true })
+    }, {
+        ourID: wowbot.instanceID
+    })
+
+    // finis
+
+    wowbot
+};
+
+
+/*
+ * workInit
+ *
+ * Initialize the component.
+ *
+ */
+
+function workInit(local manifest) {
+    manifest = `(InBot, MewBot, WowBot, workInit)
+
+    Naan.module.build(module.id, "worker", function(modobj, compobj) {
+        require("./browser.nlg")
+        compobj.manifest = manifest
+        modobj.exports.InBot = InBot
+        modobj.exports.MewBot = MewBot
+        modobj.exports.WowBot = WowBot
+    })
+} ();

package/frameworks/browser/workers.nlg

@@ -6,7 +6,7 @@
  *
  * column positioning:                          //                          //                      !
  *
- * Copyright (c) 2020-2023 by Richard C. Zulch
+ * Copyright (c) 2020-2026 by Richard C. Zulch
  *
  */
 
@@ -314,7 +314,7 @@ closure ScopedServiceWorker(pubID, pubVersion, callback, local scoper, result) {
     //
     //     Destroy the service worker.
     
-    worker.destroy = function destroy() {
+    scoper.destroy = function destroy() {
         scoper.serv.unregister()
         scoper.serv = false
     }
@@ -427,22 +427,22 @@ closure TrackServiceWorkers(track, pubID, pubVersion, callback, local error) {
     `(error, serviceWorker) = ScopedServiceWorker(pubID, pubVersion, callback)
     if error
         ErrorDebugLog("TrackServiceWorkers: cannot load service worker", error)
-    track.register(TrackedScope, "V-Site")
+    track.register("V-Site", TrackedScope)
     serviceWorker
 };
 
 
 /*
- * workInit
+ * worksInit
  *
  *     Initialize the debugger page.
  *
  */
 
-function workInit(local manifest) {
+function worksInit(local manifest) {
 
     manifest = `(ServiceWorker, ScopedServiceWorker, findTrackedScope, TrackedScope,
-        TrackServiceWorkers, workInit)
+        TrackServiceWorkers, worksInit)
 
     Naan.module.build(module.id, "workers", function(modobj, compobj) {
         require("./browser.nlg")

package/frameworks/browser/ws_client.nlg

@@ -5,7 +5,7 @@
  *
  * column positioning:                          //                          //                      !
  *
- * Copyright (c) 2023-2024 by Richard C. Zulch
+ * Copyright (c) 2023-2026 by Richard C. Zulch
  *
  */
 
@@ -13,11 +13,14 @@
 /*
  * WebSocket
  *
- * Create a WebSocket client connection object using the existing HTTPS connection.
+ * Create a WebSocket client connection object.
+ *
+ * Optional, default Host:
+ *      host:       <string>                    // host:port
  *
  * Options:
  *  {
- *      host:       <string>                    // host:port
+ *      wss:        <boolean>                   // true to use secure connection
  *      onopen:     <proc>(e)                   // connection has opened
  *      onmessage:  <proc>(e, message)          // message received
  *      onerror:    <proc>(e)                   // error occurred
@@ -28,12 +31,14 @@
  *
  */
 
-closure WebSocket(options, local wsock) {
+closure WebSocket(host, options, local wsock) {
     global(window)
     wsock = new(object, this)
     options = new(options) || { }
-    if !options.host
-        options.host = window.location.host
+    if !host {
+        host = window.location.host
+        options.wss = window.location.protocol == "https:"
+    }
 
     // connect
     //
@@ -42,10 +47,10 @@ closure WebSocket(options, local wsock) {
     wsock.connect = closure connect(local url, pending) {
         if wsock.ws
             return (list(false, { open: true }))
-        if window.location.protocol == "https:"
-            url = "wss://${options.host}${options.querys||''}"
+        if options.wss
+            url = "wss://${host}${options.querys||''}"
         else
-            url = "ws://${options.host}${options.query||''}"
+            url = "ws://${host}${options.query||''}"
         wsock.ws = xnew(window.WebSocket, url)
         pending = new(nonce)
     
@@ -58,7 +63,7 @@ closure WebSocket(options, local wsock) {
 
         // onmessage
         // A message was received from the worker via WebSockets.
-        wsock.ws.onmessage = closure onmessage(e, message) {
+        wsock.ws.onmessage = closure onmessage(e, local message) {
             try {
                 message = new(JSONparse(e.data))
             } catch {

package/frameworks/client/apiclient.nlg

@@ -2,43 +2,65 @@
  * apiclient.nlg
  * Naanlib/frameworks/client
  *
- *     Access to Nide API with specified HTTP client.
+ * Access to Nide API with specified HTTP client.
  *
  * column positioning:                          //                          //                      !
  *
- * Copyright (c) 2017-2025 by Richard C. Zulch
+ * Copyright (c) 2017-2026 by Richard C. Zulch
  *
  */
 
 
+// Globals
+
+serviceMod;;
+
+
 /*
  * APIClient
  *
- *     Make an API client object.
+ * Make an API client object. If you want websockets, and you do, call connect() on the object.
  *
  * Options:
  *  {
  *      url:            <string>                // hostname or URL of the remote server
  *      guid:           <string>                // shared secret for access to remote server
- *      instanceID:     <string>                // optional UUID for our client; can be persisted by caller
  *  }
  *
  */
 
-closure APIClient(options, local client, url, guid) {
-    global(App)
+closure APIClient(imp, options, local client, url, guid) {
+    global(App, serviceMod)
     client = new(object, this)
+    options = merge({
+    }, options)
     url = options.url
     if !url.match(RegExp("^https?:\/\/", "i"))
         url = "http://${url}"                                               // a protocol is required
     if url.slice(-1) != "/"
         url = url.concat("/")                                               // must end in "/"
     client.url = url
+    options.url = url
     client.guid = options.guid
-    client.instanceID = options.instanceID || UUID()                        // our client's unique ID
     client.notifyAfter = 0
     client.requester = clirRequester()
 
+    //
+    // connect
+    //
+
+    client.connect = function connect(error) {
+        if !client.wesc
+            client.wesc = WebSocketClient(options, imp)
+        `(error) = client.wesc.connect()
+        if error {
+            ErrorDebuglog("APIClient: cannot connect to", url, error)
+            return (list(error))
+        }
+        client.serverID = client.wesc.serverID                              // serverID
+        list(false, { connected: true })
+    }
+
     // clientRequest() - append our guid to the headers
 
     closure clientRequest(url, reqops) {
@@ -152,24 +174,204 @@ closure APIClient(options, local client, url, guid) {
         else
             callback(error, content)
     }
+    
+    // destroy
+    //
+    // Close down the client and release all resources.
+    //
+    client.destroy = closure destroy() {
+        debuglog("API client destroyed")                                    // ### not pretty, but uncommon
+        client.wesc.destroy()
+        client.wesc = false
+    }
+    
+    // finis
 
     client
 };
 
 
+/* 
+ * WebSocketClient
+ *
+ * WebSocket client for websocket communications with a server. The Instance Messaage Processor (IMP)
+ * handles routing between instances using intermediaries.
+ *
+ * Options:
+ *  {
+ *      url:            <string>                // hostname or URL of the remote server
+ *      guid:           <string>                // shared secret for access to remote server
+ *  }
+ *
+ */
+
+closure WebSocketClient(options, imp, local wesc, ws, pending) {
+    global(js)
+    wesc = new(object, this)
+
+    // reconnect
+    //
+    // Attempt to reconnect if needed, returning false on success or an error tuple otherwise.
+    //
+    function reconnect() {
+        if !ws || wesc.fatal || pending {
+            connect()                                                       // try to connect
+            if wesc.fatal
+                return (list(wesc.fatal))
+        }
+        false
+    }
+
+    // connect
+    //
+    // Establish a websocket connection with the host.
+    //
+    wesc.connect = closure connect(local url, result) {
+        if ws {
+            if pending
+                return (pending.wait())                                     // connect in process
+            if !wesc.fatal
+                return(list(false, { connected: true }))                    // already open
+        }
+        try {
+            url = xnew(js.w.URL, options.url)
+        } catch {
+            return(list(Error("invalid URL ${options.url}", exception)))
+        }
+        if url.protocol == "https:"
+            url.protocol = "wss:"
+        else
+            url.protocol = "ws:"
+        ws = xnew(js.w.WebSocket, url.href)
+        if wesc.fatal
+            debuglog("WebSocketClient reopen")                              // ### not pretty to see this
+        wesc.fatal = false
+        pending = new(nonce)
+
+        // onopen
+        // The WebSocket connection is now open.
+        ws.onopen = function onopen(e) {
+            if wesc.impconn {
+                result = wesc.impconn.reopen()
+                pending.signal(result)
+                return
+            }
+            wesc.impconn = imp.requester(function(data) {
+                if !pending && reconnect()                                  // !pending means not opening/reopening
+                    return                                                  // failed to reconnect
+                ws.send(js.w.JSON.stringify(data))
+                list(false, { sent: true })
+            }, {
+                secret: options.guid
+                label: "api-server"
+            })
+            wesc.impconn.addEventListener("active", function (event, info) {
+                wesc.serverID = info.destID                                 // serverID we connected to
+                pending.signal(list(false, { ok: true }))
+                pending = false
+            })
+        }
+
+        // onmessage
+        // A message was received via WebSockets.
+        ws.onmessage = function onmessage(e, local error, message) {
+            `(error, message) = JsonParse(e.data)
+            if !error {
+                message = new(message)
+                if wesc.impconn.dispatch(message)
+                    return
+            }
+            pending.signal(list(Error("incompatible responder")))
+            pending = false
+            debuglog("socket message:", e.data)                             // unexpected incoming data
+        }
+
+        // onerror
+        // An error occurred on the WebSocket connection.
+        // This can happen in normal operation when the connection times out.
+        ws.onerror = function onerror(e) {
+            if !wesc.fatal
+                wesc.fatal = Error("websocket failed", e)
+            pending.signal(list(wesc.fatal))
+            pending = false
+        }
+        
+        // onclose
+        // The WebSocket connection was closed.
+        ws.onclose = function onclose(e) {
+            // if e.code != 1000 && e.code != 1001 && e.code != 1005 && e.code != 1006
+                debuglog("WebSocketClient: closed:", e.code, e.reason)      // ### not pretty to see this
+            ws = false
+            if !wesc.fatal
+                wesc.fatal = Error("websocket closed", e.code, e.reason)
+            pending.signal(list(wesc.fatal))
+            pending = false
+        }
+
+        result = pending.wait(10000, list(Error("IMP connection timeout")))
+        pending = false
+        result
+    }
+
+    // close
+    //
+    // Close the connection, but can be opened again with connect().
+    //
+    wesc.close = function close() {
+        if ws
+            ws.close(1000)                                                  // 1000: normal close
+        ws = false
+    }
+    
+    // destroy
+    //
+    // Destroy the connection permanently.
+    //
+    wesc.destroy = function destroy() {
+        close()
+        wesc.impconn.destroy()
+        wesc.impconn = false
+    }
+
+    // send
+    //
+    // Send a message, returning result tuple.
+    //
+    wesc.send = closure send(data) {
+        if reconnect()
+            return                                                          // failed to reconnect
+        wesc.impconn.send(data)
+    }
+
+    // sendRaw
+    //
+    // Send a message with reconnect but no routing. Returns a result tuple.
+    //
+    wesc.sendRaw = closure sendRaw(data) {
+        if reconnect()
+            return                                                          // failed to reconnect
+        ws.send(data)
+    }
+
+    // finis
+    wesc
+};
+
+
 /*
  * apicInit
  *
- *     Initialize the apic component.
+ * Initialize the apiclient component.
  *
  */
 
 function apicInit(local manifest) {
 
-    manifest = `(APIClient, apicInit)
+    manifest = `(APIClient, WebSocketClient, apicInit)
 
     Naan.module.build(module.id, "apiclient", function(modobj, compobj) {
         Naan.module.require("./client.nlg")
+        serviceMod = Naan.module.require("naanlib:frameworks/service/imp.nlg")
         compobj.manifest = manifest
         modobj.exports.APIClient = APIClient
     })