render-workflows-dart 0.8.2

package/examples/default/tasks.dart

@@ -0,0 +1,39 @@
+import 'render_dart.dart';
+
+/// Your Render Workflows tasks, in Dart.
+///
+/// Arguments and return values must be JSON-serialisable, and Render caps a
+/// single invocation's input at 4 MB.
+void main() {
+  // A leaf task: pure computation.
+  task('calculateSquare', (args) async {
+    final n = args[0]! as int;
+    print('calculateSquare($n)');
+    return n * n;
+  });
+
+  // A parent task. Every callTask becomes its own task run on its own
+  // instance, which is how you fan work out across Render.
+  task('sumSquares', (args) async {
+    final values = args[0]! as List<Object?>;
+
+    var total = 0;
+    for (final v in values) {
+      final square = await callTask('calculateSquare', [v]);
+      total += square! as int;
+    }
+    return total;
+  });
+
+  // Options are typed and validated before they reach Render.
+  task(
+    'flaky',
+    (args) async {
+      throw StateError('this always fails, to show error reporting');
+    },
+    retry: const Retry(maxRetries: 2, waitDurationMs: 1000),
+    plan: TaskPlan.starter,
+  );
+
+  start();
+}

package/examples/http/README.md

@@ -0,0 +1,26 @@
+# http
+
+Calling external APIs from a task. No native compilation needed.
+
+`package:http` works under dart2js because its web implementation goes through
+the platform's networking rather than `dart:io` sockets. `dart:io`'s
+`HttpClient` does **not** — it compiles and then throws on first use, which is
+why the build refuses a direct `dart:io` import.
+
+| Task | Shows |
+| --- | --- |
+| `fetchRepo` | One request, with a timeout, and a real error on a bad status |
+| `fetchWithRetry` | Retrying only what is worth retrying, with backoff |
+| `fetchMany` | Overlapping requests — I/O concurrency needs no extra cores |
+
+```bash
+npm install && npx render-dart dev
+render workflows start fetchRepo --local --input='["dart-lang/sdk"]'
+```
+
+Uses GitHub's public API, which is rate-limited without a token — fine for a
+demonstration.
+
+**Retry here, or Render's?** `Retry` on the task re-runs the whole thing, which
+is right when a task fails. Retrying one request inside a task, as
+`fetchWithRetry` does, avoids paying for another run.

package/examples/http/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+build/
+.dart_tool/
+.dart-sdk/
+pubspec.lock
+.env
+.DS_Store

package/examples/http/index.js

@@ -0,0 +1,2 @@
+// Render runs this as the start command.
+require('render-dart/runtime').runTasks('./build/tasks.js');

package/examples/http/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "render-dart-http-example",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Calling external APIs from a Render Workflows task written in Dart",
+  "scripts": {
+    "build": "render-dart build",
+    "start": "node index.js",
+    "dev": "render-dart dev"
+  },
+  "dependencies": {
+    "@renderinc/sdk": "^0.6.0",
+    "render-dart": "^0.7.1"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/examples/http/pubspec.yaml

@@ -0,0 +1,13 @@
+name: render_dart_http_example
+description: Calling external APIs from a Render Workflows task.
+publish_to: none
+version: 0.1.0
+
+environment:
+  sdk: ^3.12.0
+
+dependencies:
+  # Works under dart2js because its web implementation goes through the
+  # browser's networking rather than dart:io sockets. This is the reason
+  # HTTP needs no native task.
+  http: ^1.2.0

package/examples/http/tasks.dart

@@ -0,0 +1,100 @@
+import 'dart:convert';
+
+import 'package:http/http.dart' as http;
+
+import 'render_dart.dart';
+
+/// Calling an external API from a task.
+///
+/// `package:http` works under dart2js — its web implementation goes through
+/// the browser's networking, which render-dart's runtime provides on Node. That
+/// is why fetching a URL needs no native task, while touching a file or a
+/// socket does.
+///
+/// `dart:io`'s `HttpClient` does **not** work: it compiles and then throws
+/// `Unsupported operation` on first use. The build refuses a direct `dart:io`
+/// import for exactly this reason.
+void main() {
+  /// A single request, with a timeout.
+  ///
+  /// Render bounds a task run anyway, but a per-request timeout turns a hung
+  /// dependency into a quick, legible failure instead of burning the run's
+  /// whole budget.
+  task('fetchRepo', (args) async {
+    final name = args.isEmpty ? 'dart-lang/sdk' : args[0]! as String;
+
+    final response = await http
+        .get(
+          Uri.https('api.github.com', '/repos/$name'),
+          headers: {'accept': 'application/vnd.github+json'},
+        )
+        .timeout(const Duration(seconds: 10));
+
+    if (response.statusCode != 200) {
+      // Throwing gives Render the real message in the run record.
+      throw StateError('GitHub answered ${response.statusCode} for $name');
+    }
+
+    final json = jsonDecode(response.body) as Map<String, Object?>;
+    return {
+      'name': json['full_name'],
+      'stars': json['stargazers_count'],
+      'language': json['language'],
+      'pushedAt': json['pushed_at'],
+    };
+  });
+
+  /// Retrying on the failures that are worth retrying.
+  ///
+  /// Render's own `retry` option re-runs the whole task, which is the right
+  /// tool for a task that fails. This is the finer-grained version: retry one
+  /// request without paying for another run.
+  task('fetchWithRetry', (args) async {
+    final url = Uri.parse(args[0]! as String);
+    final attempts = args.length < 2 ? 3 : args[1]! as int;
+
+    for (var attempt = 1; ; attempt++) {
+      try {
+        final response = await http.get(url).timeout(const Duration(seconds: 10));
+
+        // 4xx will not improve by asking again; 5xx and timeouts might.
+        if (response.statusCode < 500) {
+          return {
+            'status': response.statusCode,
+            'attempts': attempt,
+            'bytes': response.bodyBytes.length,
+          };
+        }
+        if (attempt >= attempts) {
+          throw StateError('$url still answering ${response.statusCode} '
+              'after $attempt attempt(s)');
+        }
+      } catch (e) {
+        if (attempt >= attempts) rethrow;
+        print('attempt $attempt failed: $e');
+      }
+
+      // Exponential backoff, so a struggling service is not hammered.
+      await Future<void>.delayed(Duration(milliseconds: 250 * (1 << (attempt - 1))));
+    }
+  });
+
+  /// Fetching several URLs at once.
+  ///
+  /// dart2js is single-threaded, but HTTP is I/O — these overlap happily. Work
+  /// that needs actual cores is the case for a native task with isolates.
+  task('fetchMany', (args) async {
+    final urls = (args[0]! as List<Object?>).cast<String>();
+
+    final responses = await Future.wait(
+      urls.map((u) => http.get(Uri.parse(u)).timeout(const Duration(seconds: 10))),
+    );
+
+    return [
+      for (var i = 0; i < urls.length; i++)
+        {'url': urls[i], 'status': responses[i].statusCode, 'bytes': responses[i].bodyBytes.length},
+    ];
+  });
+
+  start();
+}

package/examples/introspect/README.md

@@ -0,0 +1,50 @@
+# introspect
+
+A workflow task that uses Render's own API — to inspect the workspace, and to
+run a task in a *different* workflow.
+
+No native compilation. `package:render_api` runs under dart2js because it uses
+`package:http`, whose web implementation goes through the platform's
+networking.
+
+| Task | Shows |
+| --- | --- |
+| `auditDatabases` | Every Postgres instance, and how long a free one has left |
+| `listServices` | The workflow services, with the root dir that governs autodeploy |
+| `runElsewhere` | Starting a task in another workflow and waiting for it |
+
+```bash
+npm install && npx render-dart dev
+render workflows start auditDatabases --local --input='[]'
+render workflows start runElsewhere --local \
+  --input='["some-workflow/someTask", [7]]'
+```
+
+Needs `RENDER_API_KEY` on the service.
+
+## Why this is not just a curiosity
+
+`callTask` starts a **subtask of the current workflow**. Reaching a task in
+another service has no bridge equivalent — it goes through the API. So
+cross-workflow orchestration genuinely needs the SDK, and `runElsewhere` is
+the shape of it.
+
+The other natural use is scheduled operations: `auditDatabases` is one query
+away from a task that warns before a free instance is deleted.
+
+## Two things the web target forces
+
+**There is no environment**, so `Platform.environment` is unavailable and a
+client cannot pick up `RENDER_API_KEY` by itself. `node_env.dart` reaches
+Node's `process.env` through the `require` that render-dart's runtime hoists,
+and the token is passed explicitly.
+
+**Server-sent events are unreliable there**, so `runElsewhere` polls.
+
+`_awaitRun` polls the **run's own** status. A run has attempts, and an attempt
+reaches a terminal state before the run does — watching `attempts[].status`
+reports a run as finished while it is still going, which looks fine until a
+retry happens. `package:render_workflows` has `waitFor`, which does this
+properly; this example cannot depend on it yet, because that package depends on
+`render_api` by path and a path dependency cannot resolve outside its own git
+repository. That resolves when `render_api` reaches pub.dev.

package/examples/introspect/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+build/
+.dart_tool/
+.dart-sdk/
+pubspec.lock
+.env
+.DS_Store

package/examples/introspect/index.js

@@ -0,0 +1,2 @@
+// Render runs this as the start command.
+require('render-dart/runtime').runTasks('./build/tasks.js');

package/examples/introspect/node_env.dart

@@ -0,0 +1,35 @@
+/// Reading environment variables from a task.
+///
+/// dart2js selects the *web* implementation of anything platform-specific, and
+/// the web has no environment — so `Platform.environment` is unavailable and
+/// packages that read it find nothing. Node does have one; this reaches it
+/// through the `require` that render-dart's runtime hoists.
+///
+/// This is why a task must pass an API token explicitly rather than letting a
+/// client pick it up from the environment.
+library;
+
+import 'dart:js_interop';
+import 'dart:js_interop_unsafe';
+
+@JS('__require')
+external JSObject _require(String id);
+
+/// The value of [name] in the process environment, or null.
+String? nodeEnv(String name) {
+  final env = _require('node:process')['env'] as JSObject;
+  final value = env[name];
+  return value.isUndefinedOrNull ? null : (value! as JSString).toDart;
+}
+
+/// The value of [name], or a clear failure naming what to set.
+String requireEnv(String name) {
+  final value = nodeEnv(name);
+  if (value == null || value.isEmpty) {
+    throw StateError(
+      '$name is not set on this service. Add it in the Dashboard under the '
+      "service's Environment, or pass it when creating the workflow.",
+    );
+  }
+  return value;
+}

package/examples/introspect/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "render-dart-introspect-example",
+  "version": "0.1.0",
+  "private": true,
+  "description": "A Render Workflows task that uses Render's own API and Workflows SDKs",
+  "scripts": {
+    "build": "render-dart build",
+    "start": "node index.js",
+    "dev": "render-dart dev"
+  },
+  "dependencies": {
+    "@renderinc/sdk": "^0.6.0",
+    "render-dart": "^0.7.1"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/examples/introspect/pubspec.yaml

@@ -0,0 +1,23 @@
+name: render_dart_introspect_example
+description: A workflow task that inspects and orchestrates Render itself.
+publish_to: none
+version: 0.1.0
+
+environment:
+  sdk: ^3.12.0
+
+dependencies:
+  # Runs under dart2js: it uses package:http, whose web implementation goes
+  # through the browser's networking rather than dart:io sockets. So these
+  # tasks need no native compilation.
+  #
+  # A git dependency while the package is unpublished; becomes a version
+  # constraint once it is on pub.dev.
+  #
+  # package:render_workflows would be the better tool for the waiting in
+  # runElsewhere, but it cannot be fetched this way yet: it depends on
+  # render_api by path, and a path dependency cannot resolve outside its own
+  # git repository. That resolves itself when render_api reaches pub.dev.
+  render_api:
+    git:
+      url: https://github.com/timmaffett/render_api_sdk.git

package/examples/introspect/tasks.dart

@@ -0,0 +1,144 @@
+import 'package:render_api/render_api.dart';
+
+import 'node_env.dart';
+import 'render_dart.dart';
+
+/// Tasks that inspect and orchestrate Render itself.
+///
+/// Both SDKs run under dart2js — they use `package:http`, whose web
+/// implementation goes through the browser's networking rather than dart:io
+/// sockets — so none of this needs a native task.
+///
+/// Two things follow from running on the web target:
+///
+///   * There is no environment, so the API token must be passed explicitly.
+///     `node_env.dart` reaches Node's `process.env` through the bridge.
+///   * Server-sent events are unreliable there, so `runElsewhere` polls.
+///
+/// Needs `RENDER_API_KEY` set on the service. A workflow's environment can only
+/// be set when it is created, so pass it then — `PATCH /workflows/{id}` cannot
+/// add one afterwards.
+void main() {
+  /// Reports every Postgres instance, and how long a free one has left.
+  ///
+  /// A free instance is **deleted** 30 days after creation, which is the sort
+  /// of thing worth a scheduled task rather than a diary entry.
+  task('auditDatabases', (args) async {
+    final render = RenderApi(token: requireEnv('RENDER_API_KEY'));
+    try {
+      final instances = await render.listPostgres(limit: 50);
+      final now = DateTime.now();
+
+      return [
+        for (final entry in instances)
+          {
+            'name': entry.postgres.name,
+            'id': entry.postgres.id,
+            'plan': entry.postgres.plan.wireValue,
+            'region': entry.postgres.region.wireValue,
+            'status': entry.postgres.status.wireValue,
+            'expiresInDays': entry.postgres.expiresAt == null
+                ? null
+                : entry.postgres.expiresAt!.difference(now).inDays,
+          },
+      ];
+    } finally {
+      render.close();
+    }
+  });
+
+  /// Lists the workflow services in this workspace.
+  ///
+  /// Root directory is the field worth reading: autodeploy fires only for
+  /// commits touching it.
+  task('listServices', (args) async {
+    final render = RenderApi(token: requireEnv('RENDER_API_KEY'));
+    try {
+      final workflows = await render.listWorkflows(limit: 50);
+      return [
+        for (final entry in workflows)
+          {
+            'name': entry.workflow.name,
+            'id': entry.workflow.id,
+            'rootDir': entry.workflow.buildConfig.rootDir ?? '(repo root)',
+            'autoDeploy': entry.workflow.autoDeployTrigger?.wireValue ?? 'off',
+          },
+      ];
+    } finally {
+      render.close();
+    }
+  });
+
+  /// Runs a task in a **different** workflow, and waits for it.
+  ///
+  /// This is the thing `callTask` cannot do. `callTask` starts a subtask of
+  /// *this* workflow; reaching another service means going through the API, so
+  /// cross-workflow orchestration needs the SDK rather than the bridge.
+  ///
+  /// The slug is `workflow-slug/task-name`.
+  task('runElsewhere', (args) async {
+    final slug = args[0]! as String;
+    final input = args.length < 2 ? const <Object?>[] : args[1]! as List<Object?>;
+
+    final render = RenderApi(token: requireEnv('RENDER_API_KEY'));
+    try {
+      // Render calls this operation `createTask`, but it is "run task".
+      final started = await render.createTask(
+        body: CreateTaskRequest(task: slug, input: input),
+      );
+
+      final finished = await _awaitRun(render, started.id);
+      return {
+        'taskRunId': finished.id,
+        'status': finished.status.wireValue,
+        'result': finished.results.isEmpty ? null : finished.results.first,
+        'error': finished.error,
+      };
+    } finally {
+      render.close();
+    }
+  }, timeoutSeconds: 300);
+
+  start();
+}
+
+/// Terminal states for a task run.
+///
+/// Both `completed` and `succeeded` exist in the API, which is exactly the
+/// sort of detail that makes a hand-rolled status check wrong.
+const _terminal = {
+  GetTaskRunStatus.completed,
+  GetTaskRunStatus.succeeded,
+  GetTaskRunStatus.failed,
+  GetTaskRunStatus.canceled,
+};
+
+/// Polls a task run until it finishes.
+///
+/// Watch the **run's own** status. A run has attempts, and an attempt reaches a
+/// terminal state before the run does — polling `attempts[].status` reports a
+/// run as finished while it is still going, which is a mistake that looks like
+/// it works until a retry happens.
+///
+/// `package:render_workflows` has `waitFor`, which does this properly and
+/// handles timeouts. Prefer it once that package is on pub.dev; this loop
+/// exists because a git dependency on it cannot resolve yet.
+Future<GetTaskRunResponse> _awaitRun(
+  RenderApi render,
+  String taskRunId, {
+  Duration pollInterval = const Duration(milliseconds: 500),
+  Duration timeout = const Duration(minutes: 5),
+}) async {
+  final deadline = DateTime.now().add(timeout);
+
+  while (true) {
+    final run = await render.getTaskRun(taskRunId: taskRunId);
+    if (_terminal.contains(run.status)) return run;
+
+    if (DateTime.now().isAfter(deadline)) {
+      throw StateError('$taskRunId did not finish within ${timeout.inSeconds}s '
+          '(last status: ${run.status.wireValue})');
+    }
+    await Future<void>.delayed(pollInterval);
+  }
+}

package/examples/native/README.md

@@ -0,0 +1,32 @@
+# native
+
+`dart:io`, `dart:ffi` and real isolates — the things dart2js cannot do.
+
+The implementation lives in `native/tools_impl.dart` and is compiled AOT.
+`tasks.dart` imports the generated `native/tools.dart` and calls it by name;
+nothing at the call site says it is native.
+
+| Task | Shows |
+| --- | --- |
+| `readFile` | `dart:io` — impossible under dart2js |
+| `runCommand` | Spawning a process |
+| `platformInfo` | `dart:ffi`, and what the container reports |
+| `parallelHash` | Isolates across cores, timed against the sequential version |
+
+```bash
+npm install && npx render-dart dev
+render workflows start parallelHash --local --input='[["a","b","c","d","e","f","g","h"]]'
+```
+
+## What to take from parallelHash
+
+It runs the same batch sequentially and across isolates, and returns both
+timings — 86 ms against 24 ms for eight jobs on one laptop.
+
+That is the honest case for native. It is **not** faster at plain arithmetic:
+measured on Render, V8 matches Dart AOT and beats it on small inputs. What
+native gives you is reach, and the ability to use more than one core.
+
+`platformInfo` reports `numberOfProcessors`, which is the host's core count and
+not the CPU share your container actually gets. Measure before sizing an
+isolate pool by it.

package/examples/native/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+build/
+.dart_tool/
+.dart-sdk/
+pubspec.lock
+.env
+.DS_Store

package/examples/native/index.js

@@ -0,0 +1,2 @@
+// Render runs this as the start command.
+require('render-dart/runtime').runTasks('./build/tasks.js');

package/examples/native/native/tools_impl.dart

@@ -0,0 +1,105 @@
+// Compiled AOT, so this gets the real Dart platform.
+//
+// Everything here is impossible under dart2js: files, subprocesses, FFI and
+// isolates. That is the point of a native task — not speed, but reach.
+import 'dart:ffi';
+import 'dart:io';
+import 'dart:isolate';
+
+import '../native_task.dart';
+
+/// Reads a file, which dart2js cannot do at all.
+///
+/// `dart:io` compiles under dart2js and then throws `Unsupported operation` on
+/// first use, so `render-dart build` refuses a direct import in task code.
+/// Here it is exactly what we want.
+@nativeTask
+Future<Map<String, Object?>> readFile(String path, {int previewLines = 3}) async {
+  final file = File(path);
+  if (!file.existsSync()) {
+    // Throwing gives the caller the real message, not an exit code.
+    throw ArgumentError.value(path, 'path', 'no such file');
+  }
+
+  final lines = await file.readAsLines();
+  return {
+    'path': file.absolute.path,
+    'bytes': await file.length(),
+    'lines': lines.length,
+    'preview': lines.take(previewLines).toList(),
+  };
+}
+
+/// Runs a command and reports what it did.
+///
+/// A task can also shell out through render-dart's `runProcess` without going
+/// native. Doing it here instead keeps the whole operation on one side of the
+/// boundary, which matters when the surrounding logic needs dart:io anyway.
+@nativeTask
+Future<Map<String, Object?>> runCommand(String command, List<String> args) async {
+  final result = await Process.run(command, args);
+  return {
+    'exitCode': result.exitCode,
+    'stdout': '${result.stdout}'.trim(),
+    'stderr': '${result.stderr}'.trim(),
+  };
+}
+
+/// What the platform looks like from inside a native task.
+@nativeTask
+Map<String, Object?> platformInfo() => {
+      'os': Platform.operatingSystem,
+      'version': Platform.operatingSystemVersion,
+      'dart': Platform.version.split(' ').first,
+      'abi': Abi.current().toString(),
+      // dart:ffi — the size of a native pointer on this machine.
+      'pointerSize': sizeOf<IntPtr>(),
+      // Reports the host's core count, which is not the same as the CPU share
+      // this container actually gets. Measure before sizing anything by it.
+      'numberOfProcessors': Platform.numberOfProcessors,
+      'processId': pid,
+    };
+
+/// Spreads work across isolates — real parallelism, on real cores.
+///
+/// This is the one thing native is genuinely *faster* at. dart2js inherits
+/// JavaScript's single thread, so identical work there runs one job at a time.
+/// For plain arithmetic on a single job, dart2js is as quick or quicker.
+///
+/// Runs the batch both ways so the difference is measured rather than claimed.
+@nativeTask
+Future<Map<String, Object?>> parallelHash(List<String> inputs) async {
+  final sequentialStarted = DateTime.now();
+  final sequential = [for (final s in inputs) _expensiveHash(s)];
+  final sequentialMs = DateTime.now().difference(sequentialStarted).inMilliseconds;
+
+  final parallelStarted = DateTime.now();
+  final parallel = await Future.wait(
+    inputs.map((s) => Isolate.run(() => _expensiveHash(s))),
+  );
+  final parallelMs = DateTime.now().difference(parallelStarted).inMilliseconds;
+
+  return {
+    'jobs': inputs.length,
+    'sequentialMs': sequentialMs,
+    'parallelMs': parallelMs,
+    'speedup': parallelMs == 0 ? null : (sequentialMs / parallelMs * 10).round() / 10,
+    'agree': sequential.first == parallel.first,
+    'hashes': parallel,
+  };
+}
+
+/// Deliberately slow, so the parallel version has something to show.
+///
+/// The loop count is what makes this a demonstration rather than a
+/// measurement of isolate startup: too cheap, and spawning costs more than the
+/// work itself.
+int _expensiveHash(String input) {
+  var hash = 0;
+  for (var round = 0; round < 4000000; round++) {
+    for (final unit in input.codeUnits) {
+      hash = (hash * 31 + unit + round) & 0x7fffffff;
+    }
+  }
+  return hash;
+}

package/examples/native/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "render-dart-native-example",
+  "version": "0.1.0",
+  "private": true,
+  "description": "dart:io, dart:ffi and parallel isolates from a Render Workflows task",
+  "scripts": {
+    "build": "render-dart build",
+    "start": "node index.js",
+    "dev": "render-dart dev"
+  },
+  "dependencies": {
+    "@renderinc/sdk": "^0.6.0",
+    "render-dart": "^0.7.1"
+  },
+  "renderDart": {
+    "native": [
+      "native/tools_impl.dart"
+    ]
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}