render-workflows-dart 0.8.2

package/examples/postgres/tasks.dart

@@ -0,0 +1,66 @@
+import 'render_dart.dart';
+// The natural name. Nothing here says these run in another process, or that
+// they touch dart:io — the facade resolves to a stub under dart2js.
+import 'native/db.dart';
+
+/// Render Workflows tasks backed by a Render Postgres database.
+///
+/// package:postgres cannot run under dart2js, so every one of these reaches a
+/// natively compiled binary. Nothing at the call site says so.
+///
+/// The table is created and filled by `seed/`, which runs on your machine over
+/// the database's *external* connection string. These tasks read the same rows
+/// from inside Render over the *internal* one — so a change made by a task and
+/// seen by `seed/bin/show.dart` has crossed two machines and two connections.
+void main() {
+  /// Query, optionally filtered.
+  task('listWidgets', (args) async => await listWidgets(
+        sku: args.isEmpty ? null : args[0] as String?,
+        limit: args.length < 2 ? 20 : args[1]! as int,
+      ));
+
+  /// A single aggregate row.
+  task('widgetStats', (args) async => await widgetStats());
+
+  /// Insert or update.
+  task('upsertWidget', (args) async => await upsertWidget(
+        args[0]! as String,
+        args[1]! as String,
+        args[2]! as int,
+        args[3]! as int,
+      ));
+
+  /// Update one row and return it.
+  task('restock', (args) async => await restock(
+        args[0]! as String,
+        args[1]! as int,
+      ));
+
+  /// Calls dbConnection repeatedly to show that a worker holds one Postgres
+  /// session: the backend pid stays put while the call counter climbs.
+  ///
+  /// Reconnecting per call would show a different pid every time — and pay for
+  /// a TCP handshake, TLS negotiation and authentication each round.
+  task('connectionReuse', (args) async {
+    final n = args.isEmpty ? 5 : args[0]! as int;
+    final started = DateTime.now();
+
+    final backendPids = <Object?>{};
+    Map<String, Object?> last = const {};
+    for (var i = 0; i < n; i++) {
+      last = await dbConnection();
+      backendPids.add(last['backend_pid']);
+    }
+
+    return {
+      'calls': n,
+      'ms': DateTime.now().difference(started).inMilliseconds,
+      'distinctBackendPids': backendPids.length,
+      'callsThisProcess': last['callsThisProcess'],
+      'connectionAgeMs': last['connectionAgeMs'],
+      'database': last['database'],
+    };
+  }, timeoutSeconds: 120);
+
+  start();
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "render-workflows-dart",
+  "version": "0.8.2",
+  "description": "Unofficial: write Render Workflows tasks in Dart, compiled to JavaScript. Not affiliated with or endorsed by Render.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timmaffett/render_workflows_dart.git"
+  },
+  "keywords": [
+    "render",
+    "workflows",
+    "dart",
+    "dart2js"
+  ],
+  "bin": {
+    "render-workflows-dart": "src/cli.js",
+    "render-dart": "src/cli.js"
+  },
+  "main": "src/runtime.js",
+  "exports": {
+    ".": "./src/runtime.js",
+    "./runtime": "./src/runtime.js",
+    "./toolchain": "./src/toolchain/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "runtime",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "dart"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "peerDependencies": {
+    "@renderinc/sdk": ">=0.5.0",
+    "@bjorn3/browser_wasi_shim": ">=0.2.9"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@bjorn3/browser_wasi_shim": {
+      "optional": true
+    }
+  }
+}

package/runtime/AGENTS.md

@@ -0,0 +1,141 @@
+# Working in this project
+
+Render Workflows tasks written in Dart, built by
+[`render-dart`](https://github.com/timmaffett/render_workflows_dart).
+
+Task bodies are compiled to JavaScript with `dart compile js` and registered
+through Render's official `@renderinc/sdk` on the `node` runtime. Where
+JavaScript is not enough, a task calls into Dart compiled natively.
+
+## Commands
+
+```bash
+npx render-dart build         # compile; --force skips the freshness check
+npx render-dart dev           # build, then start Render's local task server
+npx render-dart dart          # which Dart this project uses, and why
+render workflows tasks list --local
+render workflows start <task> --local --input='[1, 2]'
+```
+
+No Dart installation is needed. If one is on `PATH` the build uses it;
+otherwise an SDK is fetched into `node_modules`. Either way the build prints
+which version it used and where it came from, so `render-dart dart` is only
+needed before building.
+
+To pin a version, put it in `package.json` — that is the form that travels
+with the project:
+
+```json
+"renderDart": { "dartVersion": "3.13.1" }
+```
+
+`--dart-version` and `RENDER_DART_VERSION` override it, in that order, for
+trying one without a commit. **A version asked for explicitly beats a Dart on
+`PATH`** and is downloaded if it has to be, so a pin means the same version
+here and on Render. `latest` and the channel names work too, but an exact
+version is the one that reproduces.
+
+## Writing a task
+
+`tasks.dart` registers functions by name and must end with `start()`:
+
+```dart
+task('doThing', (args) async => args[0]! as int * 2);
+```
+
+Arguments and return values are JSON. Render caps one invocation's input at
+4 MB. `callTask('other', [...])` starts a **subtask of this workflow**, each on
+its own instance — that is how work fans out.
+
+## The rule that catches people
+
+**`dart:io` does not work in task code.** It compiles under dart2js and then
+throws `Unsupported operation` on first use, so the build refuses a direct
+import. That rules out files, sockets, subprocesses and any package needing
+them.
+
+Three ways forward:
+
+| Need | Use |
+| --- | --- |
+| HTTP | `package:http` — works, it goes through the platform's networking |
+| A package shipping a `.wasm` | just use it; modules resolve automatically |
+| Files, FFI, a database, real parallelism | a **native task** |
+
+## Native tasks
+
+Write the implementation in `native/<name>_impl.dart`, annotate top-level
+functions, and list the file in `renderDart.native` in `package.json`:
+
+```dart
+// native/tools_impl.dart
+import 'dart:io';
+import '../native_task.dart';
+
+@nativeTask
+Map<String, Object?> inspect(String path) => {'bytes': File(path).lengthSync()};
+```
+
+```dart
+// tasks.dart — nothing here says it is native
+import 'native/tools.dart';
+
+task('inspect', (args) async => await inspect(args[0]! as String));
+```
+
+The build generates `native/tools.dart` and `native/tools.stub.dart`. Do not
+edit or commit them.
+
+- **Always `await`** a native task; the stub returns a `Future` where the
+  implementation may not.
+- **Return JSON-representable types only.** `DateTime` is not — convert to an
+  ISO-8601 string. Anything unsupported is rejected at build time, naming the
+  parameter.
+- **`@NativeTask(worker: true)`** keeps the process alive between calls, which
+  matters for anything holding a connection. It also keeps top-level state, so
+  one call can observe what the last left behind.
+
+**Native is not faster at arithmetic.** Measured on Render, V8 matches Dart AOT
+on integer work and beats it at small n. Choose native for *capability* — or
+for parallelism, which is the one real speed win, since dart2js is
+single-threaded.
+
+## Reaching a database
+
+`package:postgres` cannot run under dart2js at all — it needs a raw socket, and
+pub.dev marks it `runtime:native-aot` with no `runtime:web`. So a database
+needs a native task, holding the connection open with `worker: true`.
+
+`render-dart init db --template postgres` scaffolds a working version, seeder
+included.
+
+The connection string belongs in `DATABASE_URL` on the service, set to the
+database's **internal** string. A workflow's environment can only be set when
+the service is created; afterwards, the Dashboard is the only route.
+
+## Deploying
+
+| Field | Value |
+| --- | --- |
+| Runtime | Node |
+| Build Command | `npm install && npm run build` |
+| Start Command | `node index.js` |
+| Root Directory | where this `package.json` lives |
+
+**Autodeploy fires only for commits touching the root directory.** A commit
+elsewhere being ignored is correct, not a broken webhook.
+
+## Do not commit
+
+`build/`, `node_modules/`, and the generated `native/*.dart` files. The build
+regenerates all of them and maintains a `native/.gitignore`.
+
+`render_dart.dart` and `native_task.dart` are render-dart's bridge files. They
+are boilerplate — the build refreshes them when missing and warns when a local
+copy is older than the installed package.
+
+## More
+
+Runnable examples covering HTTP, native tasks, Postgres, WebAssembly and
+calling Render's own API from a task:
+<https://github.com/timmaffett/render_workflows_dart/tree/main/examples>

package/runtime/CLAUDE.md

@@ -0,0 +1,2 @@
+See [AGENTS.md](AGENTS.md) — the guidance for working in this project lives there,
+so there is one file to keep current rather than two.

package/runtime/native_task.dart

@@ -0,0 +1,115 @@
+/// The native side of a render-dart native task.
+///
+/// This file is boilerplate — you shouldn't need to edit it. A file compiled
+/// AOT by `render-dart build` runs a generated `main()` that calls
+/// [nativeTaskMain] with its `@nativeTask` functions.
+///
+/// The protocol is JSONL: one JSON object per line, in and out. That framing
+/// is what lets the same binary serve a one-shot call and, later, a persistent
+/// worker — a one-shot writes a line and reads a line, a worker just keeps
+/// looping.
+///
+///   → {"id":1,"method":"inspect","args":["a.png"],"named":{"sha":true}}
+///   ← {"id":1,"$log":"reading a.png"}
+///   ← {"id":1,"$ok":{"bytes":8192}}
+///
+/// Every message carries an `id` even though a one-shot call has only one
+/// request in flight, so nothing about the wire format changes when a worker
+/// starts multiplexing several.
+library;
+
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+/// Marks a top-level function as callable from a dart2js task.
+///
+/// Parameters and the return value cross a JSON boundary, so they must be
+/// JSON-representable: bool, int, double, num, String, List<T>, Map<String, T>,
+/// Object?, dynamic, or Future<T> of those. `render-dart build` rejects
+/// anything else by name rather than letting it fail as a decode error at run
+/// time.
+class NativeTask {
+  const NativeTask({this.worker, this.idleTimeout, this.timeout});
+
+  /// Keep the executable alive between calls.
+  ///
+  /// Much faster in a loop — 10 ms against 132 ms over 20 calls on Render —
+  /// but the process keeps its top-level state, so call N can observe what
+  /// call N-1 left behind and a leak is never cleaned up by process exit.
+  /// Defaults to false.
+  final bool? worker;
+
+  /// How long an idle worker lingers before it is reaped. Defaults to 30 s.
+  final Duration? idleTimeout;
+
+  /// How long one call may take before it is abandoned. Unset means no limit.
+  final Duration? timeout;
+}
+
+/// The annotation itself, for the common case with no options: `@nativeTask`.
+const nativeTask = NativeTask();
+
+/// What a generated dispatcher entry looks like.
+typedef NativeHandler = Future<Object?> Function(
+  List<Object?> args,
+  Map<String, Object?> named,
+);
+
+/// Serves JSONL requests on stdin until it closes.
+///
+/// Handlers run one at a time. A native task therefore never has to be
+/// reentrant, which is the reason worker mode can reuse this unchanged.
+Future<void> nativeTaskMain(
+  List<String> argv,
+  Map<String, NativeHandler> handlers,
+) async {
+  final out = stdout;
+
+  final lines = stdin.transform(utf8.decoder).transform(const LineSplitter());
+
+  await for (final line in lines) {
+    if (line.trim().isEmpty) continue;
+
+    Object? id;
+    try {
+      final request = jsonDecode(line) as Map<String, Object?>;
+      id = request['id'];
+      final method = request['method'] as String?;
+      final args = (request['args'] as List?)?.cast<Object?>() ?? const [];
+      final named = (request['named'] as Map?)?.cast<String, Object?>() ?? const {};
+
+      final handler = handlers[method];
+      if (handler == null) {
+        _write(out, {
+          'id': id,
+          r'$err': 'no @nativeTask named "$method" in this executable',
+          r'$known': handlers.keys.toList(),
+        });
+        continue;
+      }
+
+      // print() from a task body would otherwise land on stdout and corrupt
+      // the framing, so it is rerouted to a $log line instead of becoming a
+      // baffling parse error on the Node side.
+      final result = await runZoned(
+        () => handler(args, named),
+        zoneSpecification: ZoneSpecification(
+          print: (_, __, ___, String message) =>
+              _write(out, {'id': id, r'$log': message}),
+        ),
+      );
+
+      _write(out, {'id': id, r'$ok': result});
+    } catch (e, stackTrace) {
+      // Mirrors the {$ok}/{$err} envelope the JS boundary uses, for the same
+      // reason: a real message is worth more than a generic failure.
+      _write(out, {'id': id, r'$err': '$e', r'$stack': '$stackTrace'});
+    }
+  }
+}
+
+void _write(IOSink out, Map<String, Object?> message) {
+  // jsonEncode escapes newlines, so one message is always exactly one line.
+  out.writeln(jsonEncode(message));
+}