@rdfc/js-runner 3.0.2 → 3.0.4-remote

package/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npm run:*)",
+      "Bash(chmod +x *)",
+      "Bash(node bin/server.js)",
+      "Bash(echo \"exit:$?\")"
+    ]
+  }
+}

package/README.md

@@ -1,5 +1,9 @@
 # JavaScript runner for RDF-Connect
 
+[![Build and tests with Node.js](https://github.com/rdf-connect/js-runner/actions/workflows/build-test.yml/badge.svg)](https://github.com/rdf-connect/js-runner/actions/workflows/build-test.yml) [![npm](https://img.shields.io/npm/v/@rdfc/js-runner.svg?style=popout)](https://npmjs.com/package/@rdfc/js-runner)
+
+This package provides a JavaScript runner implementation for RDF-Connect, which allows you to run JavaScript/TypeScript processors in your [RDF-Connect](https://github.com/rdf-connect/rdf-connect) pipeline.
+
 ## Usage
 
 To use the JavaScript (Node or Bun) runner for RDF-Connect, you need to have a pipeline configuration that includes JavaScript/TypeScript processors.
@@ -28,6 +32,42 @@ You can install the js-runner package using the following command:
 npm install @rdfc/js-runner
 ```
 
+### Remote runner usage
+
+The js-runner can also be used as a remote runner. To do this, start the runner server using `npx js-runner-server ./server.ttl`.
+This starts the remote server as configured in `server.ttl`
+
+```turtle
+@prefix rdfc: <https://w3id.org/rdf-connect#>.
+
+<> a rdfc:JsRunnerServer;
+  rdfc:port 3000;
+  # one or more processor definition files to host
+  rdfc:processorConfig <./processors.ttl>.
+```
+
+This enables the user to configure the pipeline just like a normal pipeline. The runner definition is automatically available at `localhost:{PORT}`.
+
+```turtle
+@prefix owl: <http://www.w3.org/2002/07/owl#>.
+@prefix rdfc: <https://w3id.org/rdf-connect#>.
+
+# the endpoint serving the example configuration
+@prefix runner: <http://localhost:3000/>.
+
+# import the runner and the processor definitions
+<> owl:imports runner:, runner:processors.ttl.
+
+# setup the pipeline
+<> a rdfc:Pipeline;
+  rdfc:consistsOf [
+    rdfc:processor <logProc>, <sendProc>;
+    rdfc:instantiates runner:runner;
+  ].
+```
+
+There is an example in `./examples/echo`, start the server with `npx js-runner-server ./server.ttl` and run the pipeline `npx rdfc ./remote_pipeline.ttl`.
+
 ## Logging
 
 The JavaScript runner and processors use the `winston` logging library for logging.
@@ -86,7 +126,7 @@ JavaScript/TypeScript processors must include the JavaScript specific configurat
 
 The JavaScript runner is implemented in TypeScript.
 The source code is contained in the `src` folder.
-The main cli entry point is the `bin/runner.js` file, which you can also run after installation of the package using `npx js-runner`.
+The main cli entry points are the `bin/runner.js` and `bin/server.js` files, which you can also run after installation of the package using `npx js-runner` and `npx js-runner-server` respectively.
 
 If you want to get started with the development of the js-runner, you can clone the repository and install the dependencies using the following commands.
 

package/__tests__/echoProcessor.test.ts

@@ -70,12 +70,11 @@ describe('EchoProcessor', () => {
 
     const msgs: string[] = []
 
-      ; (async () => {
-        for await (const m of outputReader.strings()) {
-          msgs.push(m)
-        }
-      })()
-
+    ;(async () => {
+      for await (const m of outputReader.strings()) {
+        msgs.push(m)
+      }
+    })()
 
     await inputWriter.string('Hello')
     expect(msgs).toEqual(['Hello'])
@@ -107,13 +106,13 @@ describe('EchoProcessor', () => {
 
     const msgs: string[] = []
 
-      ; (async () => {
-        for await (const m of outputReader.strings()) {
-          msgs.push(m)
-        }
-      })()
+    ;(async () => {
+      for await (const m of outputReader.strings()) {
+        msgs.push(m)
+      }
+    })()
 
-    const gen = async function*() {
+    const gen = async function* () {
       yield encoder.encode('Hello')
       yield encoder.encode('World')
     }

package/bin/runner.js

@@ -2,7 +2,13 @@
 
 import { start } from '../lib/client.js'
 
+// One-shot CLI mode: connect to an existing orchestrator, run processors, then exit.
+// process.exit is needed because grpc-js keeps the event loop alive after client.close().
 const host = process.argv[2]
 const uri = process.argv[3]
-
 start(host, uri)
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error(err)
+    process.exit(1)
+  })

package/bin/server.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { serve } from '../lib/server.js'
+
+const configPath = process.argv[2]
+if (!configPath) {
+  console.error('Usage: js-runner-server <config>')
+  process.exit(1)
+}
+serve(configPath).catch((err) => {
+  console.error(err)
+  process.exit(1)
+})