render-workflows-dart 0.8.2

package/examples/native/pubspec.yaml

@@ -0,0 +1,7 @@
+name: render_dart_native_example
+description: Reaching dart:io, dart:ffi and isolates from a Render Workflows task.
+publish_to: none
+version: 0.1.0
+
+environment:
+  sdk: ^3.12.0

package/examples/native/tasks.dart

@@ -0,0 +1,35 @@
+import 'render_dart.dart';
+// The plain name. Nothing here says these run in another process.
+import 'native/tools.dart';
+
+/// Tasks backed by natively compiled Dart.
+///
+/// `render-dart build` compiles `native/tools_impl.dart` to an executable and
+/// generates `native/tools.dart`, which resolves to a process call under
+/// dart2js and to the real function when compiled natively.
+///
+/// Always `await` one: the stub returns a `Future` where the implementation
+/// may return a plain value.
+void main() {
+  /// Reading a file — impossible from dart2js.
+  task('readFile', (args) async => await readFile(
+        args[0]! as String,
+        previewLines: args.length < 2 ? 3 : args[1]! as int,
+      ));
+
+  /// Shelling out.
+  task('runCommand', (args) async => await runCommand(
+        args[0]! as String,
+        (args.length < 2 ? const <Object?>[] : args[1]! as List<Object?>).cast<String>(),
+      ));
+
+  /// dart:ffi and platform details.
+  task('platformInfo', (args) async => await platformInfo());
+
+  /// Real parallelism across cores.
+  task('parallelHash', (args) async => await parallelHash(
+        (args[0]! as List<Object?>).cast<String>(),
+      ), timeoutSeconds: 120);
+
+  start();
+}

package/examples/postgres/README.md

@@ -0,0 +1,73 @@
+# postgres
+
+Reading and writing a Render Postgres database from a Dart workflow task.
+
+This is the clearest case for native tasks existing. `package:postgres` speaks
+the wire protocol over a raw socket, so it needs `dart:io` — pub.dev marks it
+`runtime:native-aot` and `runtime:native-jit`, with **no** `runtime:web`. It
+cannot run under dart2js at all, and there is no WebAssembly build to fall back
+on. Native or nothing.
+
+## The two halves
+
+`seed/` runs on **your machine**, over the database's *external* connection
+string. It creates the table and fills it.
+
+The tasks run **on Render**, over the *internal* one. So when a task changes a
+row and `seed/bin/show.dart` sees it, the data has crossed two machines and two
+connections — which is the thing worth demonstrating.
+
+| Task | Shows |
+| --- | --- |
+| `listWidgets` | A parameterised query |
+| `widgetStats` | An aggregate |
+| `upsertWidget` | Insert or update |
+| `restock` | `update … returning`, in one statement so concurrent runs cannot lose an update |
+| `dbConnection` | `pg_backend_pid()` — proof the connection is held |
+
+## Running it
+
+```bash
+cd seed
+export RENDER_API_KEY=rnd_...        # the connection string is fetched for you
+dart pub get && dart run bin/seed.dart
+
+cd ..
+export DATABASE_URL=<external connection string>
+npm install && npx render-dart dev
+render workflows start widgetStats --local --input='[]'
+```
+
+`seed.dart` is re-runnable: `create table if not exists`, rows upserted by sku.
+That matters because a **free** Render Postgres instance is deleted 30 days
+after creation, so this is the recipe for rebuilding the demo.
+
+## Deploying
+
+`DATABASE_URL` must hold the database's **internal** connection string. A
+workflow's environment can only be set when the service is created — pass it
+then, because `PATCH /workflows/{id}` cannot add one afterwards, leaving only
+the Dashboard.
+
+## Three things that will bite
+
+**Worker mode is doing real work here.** Every task declares
+`@NativeTask(worker: true)`, so the process stays alive and the TCP handshake,
+TLS negotiation and authentication happen once rather than per call.
+`dbConnection` proves it: the backend pid holds steady while a counter climbs.
+
+**A held connection can die** — idle timeout, a restart, a deploy. `_db()`
+checks and reconnects rather than surfacing a broken socket. That is the honest
+cost of keeping state in a worker.
+
+**`timestamptz` arrives as a `DateTime`, which is not JSON.** Rows are
+converted to ISO-8601 strings before returning; otherwise the build rejects the
+signature — correct, but puzzling if unexpected.
+
+## A note on the connection string
+
+Render's *internal* string carries no port, and `Uri.port` reports `0` for
+that, which is not a port. `seed/lib/src/connect.dart` applies 5432 explicitly.
+`Connection.openFromUrl` exists but takes TLS from an `sslmode` query parameter
+Render's strings do not carry, so the endpoint is built by hand with
+`SslMode.require`.

package/examples/postgres/gitignore

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

package/examples/postgres/index.js

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

package/examples/postgres/native/db_impl.dart

@@ -0,0 +1,205 @@
+// Database access for the workflow tasks, compiled AOT.
+//
+// This is the case where native is not a convenience but the only option:
+// package:postgres speaks the wire protocol over a raw socket, so it needs
+// dart:io. pub.dev marks it runtime:native-aot and runtime:native-jit, with no
+// runtime:web — under dart2js it cannot run at all.
+//
+// Every task here declares worker: true. That keeps one process alive, and
+// with it one open connection, so the TCP handshake, TLS negotiation and
+// Postgres authentication happen once instead of on every call.
+import 'dart:io';
+
+import 'package:postgres/postgres.dart';
+
+import '../native_task.dart';
+
+const _worker = NativeTask(
+  worker: true,
+  idleTimeout: Duration(minutes: 2),
+  timeout: Duration(seconds: 30),
+);
+
+Connection? _connection;
+int _calls = 0;
+DateTime? _connectedAt;
+
+/// The held connection, opened on first use and re-established if it died.
+///
+/// A worker's state surviving between calls is what makes it fast, and also
+/// what makes this necessary: Postgres can hang up on an idle client, a deploy
+/// restarts the database, and the socket is then dead in a way that only shows
+/// up on the next query. Checking beats surfacing a broken pipe to the caller.
+Future<Connection> _db() async {
+  final existing = _connection;
+  if (existing != null && existing.isOpen) return existing;
+
+  if (existing != null) {
+    stderr.writeln('[db] connection was closed, reconnecting');
+    _connection = null;
+  }
+
+  final url = Platform.environment['DATABASE_URL'];
+  if (url == null || url.isEmpty) {
+    throw StateError(
+      'DATABASE_URL is not set on this service. It should hold the database\'s '
+      'internal connection string — set it when creating the workflow, or in '
+      'the Dashboard under the service\'s Environment.',
+    );
+  }
+
+  final uri = Uri.parse(url);
+  final userInfo = uri.userInfo.split(':');
+
+  final connection = await Connection.open(
+    Endpoint(
+      host: uri.host,
+      // Render's internal connection string carries no port, and Uri reports 0
+      // rather than null for that, which is not a port.
+      port: uri.hasPort ? uri.port : 5432,
+      database: uri.pathSegments.isEmpty ? 'postgres' : uri.pathSegments.first,
+      username: userInfo.isNotEmpty ? Uri.decodeComponent(userInfo.first) : null,
+      password: userInfo.length > 1 ? Uri.decodeComponent(userInfo[1]) : null,
+    ),
+    settings: const ConnectionSettings(
+      sslMode: SslMode.require,
+      applicationName: 'render-dart-db-test',
+      connectTimeout: Duration(seconds: 15),
+    ),
+  );
+
+  _connection = connection;
+  _connectedAt = DateTime.now();
+  return connection;
+}
+
+/// Rows come back with DateTime values, which are not JSON. Converting here
+/// keeps every task's return type inside what can cross the boundary —
+/// otherwise `render-dart build` rejects the signature, correctly but
+/// confusingly if you were not expecting it.
+Map<String, Object?> _jsonRow(ResultRow row) => {
+      for (final entry in row.toColumnMap().entries)
+        entry.key: switch (entry.value) {
+          final DateTime v => v.toIso8601String(),
+          final v => v,
+        },
+    };
+
+/// Lists widgets, newest update first, optionally filtered by sku.
+@_worker
+Future<List<Map<String, Object?>>> listWidgets({String? sku, int limit = 20}) async {
+  _calls++;
+  final db = await _db();
+
+  final result = sku == null
+      ? await db.execute(
+          Sql.named('select * from widgets order by sku limit @limit'),
+          parameters: {'limit': limit},
+        )
+      : await db.execute(
+          Sql.named('select * from widgets where sku = @sku'),
+          parameters: {'sku': sku},
+        );
+
+  return result.map(_jsonRow).toList();
+}
+
+/// A single aggregate row: how much stock there is and what it is worth.
+@_worker
+Future<Map<String, Object?>> widgetStats() async {
+  _calls++;
+  final db = await _db();
+
+  final result = await db.execute('''
+    select count(*)                        as widgets,
+           coalesce(sum(quantity), 0)      as units,
+           coalesce(sum(quantity * price_cents), 0) as value_cents,
+           max(updated_at)                 as newest_update
+    from widgets
+  ''');
+
+  return _jsonRow(result.first);
+}
+
+/// Inserts a widget, or updates it if the sku already exists.
+@_worker
+Future<Map<String, Object?>> upsertWidget(
+  String sku,
+  String name,
+  int quantity,
+  int priceCents,
+) async {
+  _calls++;
+  final db = await _db();
+
+  final result = await db.execute(
+    Sql.named('''
+      insert into widgets (sku, name, quantity, price_cents)
+      values (@sku, @name, @quantity, @priceCents)
+      on conflict (sku) do update set
+        name        = excluded.name,
+        quantity    = excluded.quantity,
+        price_cents = excluded.price_cents,
+        updated_at  = now()
+      returning *
+    '''),
+    parameters: {
+      'sku': sku,
+      'name': name,
+      'quantity': quantity,
+      'priceCents': priceCents,
+    },
+  );
+
+  return _jsonRow(result.first);
+}
+
+/// Adds [delta] to a widget's quantity and returns the row that changed.
+///
+/// Done in one statement rather than read-then-write, so two concurrent runs
+/// cannot lose an update between them.
+@_worker
+Future<Map<String, Object?>> restock(String sku, int delta) async {
+  _calls++;
+  final db = await _db();
+
+  final result = await db.execute(
+    Sql.named('''
+      update widgets
+         set quantity = quantity + @delta,
+             updated_at = now()
+       where sku = @sku
+      returning *
+    '''),
+    parameters: {'sku': sku, 'delta': delta},
+  );
+
+  if (result.isEmpty) throw ArgumentError.value(sku, 'sku', 'no widget with that sku');
+  return _jsonRow(result.first);
+}
+
+/// Proves the connection is being reused, from the server's point of view.
+///
+/// `pg_backend_pid()` is the Postgres process serving this session. If it holds
+/// steady across calls, the worker really is reusing one connection rather than
+/// reconnecting — the database-side counterpart to the process pid in
+/// nativeLoop.
+@_worker
+Future<Map<String, Object?>> dbConnection() async {
+  _calls++;
+  final db = await _db();
+
+  final result = await db.execute(
+    'select pg_backend_pid() as backend_pid, current_database() as database, '
+    'version() as server',
+  );
+  final row = _jsonRow(result.first);
+
+  return {
+    ...row,
+    'processPid': pid,
+    'callsThisProcess': _calls,
+    'connectionAgeMs':
+        _connectedAt == null ? 0 : DateTime.now().difference(_connectedAt!).inMilliseconds,
+  };
+}

package/examples/postgres/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "render-dart-postgres-example",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Reading and writing Render Postgres from a Dart workflow 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/db_impl.dart"
+    ],
+    "allowDartIoIn": [
+      "seed"
+    ]
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/examples/postgres/pubspec.yaml

@@ -0,0 +1,14 @@
+name: render_dart_postgres_example
+description: Reading and writing Render Postgres from a Dart workflow task.
+publish_to: none
+version: 0.1.0
+
+environment:
+  sdk: ^3.12.0
+
+dependencies:
+  # Speaks the Postgres wire protocol over a raw socket, so it needs dart:io.
+  # pub.dev marks it runtime:native-aot and native-jit, with no runtime:web —
+  # under dart2js it cannot run at all. That is why the tasks that use it are
+  # native, and it is the clearest case for native tasks existing.
+  postgres: ^3.5.12

package/examples/postgres/seed/bin/seed.dart

@@ -0,0 +1,56 @@
+// Creates the widgets table and fills it with sample rows.
+//
+//   dart run bin/seed.dart
+//   dart run bin/seed.dart --database-id dpg-...
+//   DATABASE_URL=postgresql://... dart run bin/seed.dart
+//
+// Safe to re-run: the table is created only if absent, and rows are upserted
+// by sku. That matters because a free Render Postgres instance is deleted 30
+// days after creation, so this is the recipe for getting the demo back.
+//
+// This is deliberately NOT a workflow task. It runs from a laptop over the
+// external connection string, which is the other half of the demonstration —
+// the tasks later read the same rows from inside Render.
+import 'dart:io';
+
+import 'package:render_dart_postgres_seed/src/connect.dart';
+import 'package:render_dart_postgres_seed/src/schema.dart';
+
+Future<void> main(List<String> args) async {
+  final databaseId = _option(args, 'database-id') ?? defaultDatabaseId;
+
+  final connectionString = await resolveConnectionString(databaseId: databaseId);
+  stdout.writeln('connecting to ${describe(connectionString)}');
+
+  final db = await openConnection(connectionString);
+  try {
+    await db.execute(createWidgetsTable);
+    stdout.writeln('table widgets is ready');
+
+    for (final widget in dummyWidgets) {
+      final result = await db.execute(
+        Sql.named(upsertWidget),
+        parameters: widget,
+      );
+      final row = result.first.toColumnMap();
+      stdout.writeln('  ${row['sku']}  ${row['name']}'
+          '  qty ${row['quantity']}'
+          '  ${_money(row['price_cents'] as int)}');
+    }
+
+    final count = await db.execute('select count(*) from widgets');
+    stdout.writeln('\n${count.first.first} row(s) in widgets');
+  } finally {
+    await db.close();
+  }
+}
+
+String _money(int cents) => '\$${(cents / 100).toStringAsFixed(2)}';
+
+String? _option(List<String> args, String name) {
+  for (var i = 0; i < args.length; i++) {
+    if (args[i] == '--$name' && i + 1 < args.length) return args[i + 1];
+    if (args[i].startsWith('--$name=')) return args[i].substring(name.length + 3);
+  }
+  return null;
+}

package/examples/postgres/seed/bin/show.dart

@@ -0,0 +1,64 @@
+// Prints what is actually in the widgets table.
+//
+//   dart run bin/show.dart
+//   dart run bin/show.dart --sku WDG-005
+//
+// Useful as the independent check on a workflow task: run a task that mutates
+// a row, then run this from your laptop and see the change. Different machine,
+// different connection string, same data.
+import 'dart:io';
+
+import 'package:render_dart_postgres_seed/src/connect.dart';
+
+Future<void> main(List<String> args) async {
+  final sku = _option(args, 'sku');
+
+  final connectionString = await resolveConnectionString();
+  final db = await openConnection(connectionString);
+
+  try {
+    final result = sku == null
+        ? await db.execute(
+            'select sku, name, quantity, price_cents, updated_at '
+            'from widgets order by sku')
+        : await db.execute(
+            Sql.named('select sku, name, quantity, price_cents, updated_at '
+                'from widgets where sku = @sku'),
+            parameters: {'sku': sku},
+          );
+
+    if (result.isEmpty) {
+      stdout.writeln(sku == null ? 'widgets is empty' : 'no widget with sku $sku');
+      return;
+    }
+
+    stdout.writeln('${'sku'.padRight(10)} ${'name'.padRight(24)} '
+        '${'qty'.padLeft(6)} ${'price'.padLeft(9)}  updated');
+    var totalCents = 0;
+    for (final row in result) {
+      final r = row.toColumnMap();
+      final quantity = r['quantity'] as int;
+      final priceCents = r['price_cents'] as int;
+      totalCents += quantity * priceCents;
+
+      stdout.writeln('${(r['sku'] as String).padRight(10)} '
+          '${(r['name'] as String).padRight(24)} '
+          '${quantity.toString().padLeft(6)} '
+          '${_money(priceCents).padLeft(9)}  '
+          '${(r['updated_at'] as DateTime).toIso8601String().substring(0, 19)}');
+    }
+    stdout.writeln('\n${result.length} row(s), inventory value ${_money(totalCents)}');
+  } finally {
+    await db.close();
+  }
+}
+
+String _money(int cents) => '\$${(cents / 100).toStringAsFixed(2)}';
+
+String? _option(List<String> args, String name) {
+  for (var i = 0; i < args.length; i++) {
+    if (args[i] == '--$name' && i + 1 < args.length) return args[i + 1];
+    if (args[i].startsWith('--$name=')) return args[i].substring(name.length + 3);
+  }
+  return null;
+}

package/examples/postgres/seed/lib/src/connect.dart

@@ -0,0 +1,93 @@
+/// Getting a connection to the Render Postgres instance.
+///
+/// Two credential sources, in order:
+///
+///   DATABASE_URL      if set, used as-is. Works offline, against a local
+///                     Postgres, or anywhere an API key is unavailable.
+///   RENDER_API_KEY    otherwise, the connection string is fetched through
+///                     package:render_api. Nothing to copy, nothing to keep in
+///                     a file, and it survives the database being recreated.
+library;
+
+import 'dart:io';
+
+import 'package:postgres/postgres.dart';
+import 'package:render_api/render_api.dart';
+
+// Callers need Sql and Connection alongside these helpers; re-exporting
+// keeps them to a single import.
+export 'package:postgres/postgres.dart' show Connection, Endpoint, Sql, SslMode;
+
+/// The example's database. An id is an identifier, not a secret.
+const defaultDatabaseId = 'dpg-da3b13gae00c73ag6t8g-a';
+
+/// Resolves a connection string without opening anything.
+///
+/// [internal] picks Render's private hostname, which only resolves from inside
+/// Render's network and in the same region. Local programs want the external
+/// one; a workflow task wants internal — faster, and it never leaves Render.
+Future<String> resolveConnectionString({
+  String databaseId = defaultDatabaseId,
+  bool internal = false,
+}) async {
+  final fromEnv = Platform.environment['DATABASE_URL'];
+  if (fromEnv != null && fromEnv.isNotEmpty) return fromEnv;
+
+  if ((Platform.environment['RENDER_API_KEY'] ?? '').isEmpty) {
+    throw StateError(
+      'Neither DATABASE_URL nor RENDER_API_KEY is set.\n'
+      '  export RENDER_API_KEY=rnd_...   and the connection string is fetched for you\n'
+      '  export DATABASE_URL=postgresql://...   to point somewhere else entirely',
+    );
+  }
+
+  final render = RenderApi();
+  try {
+    final info = await render.retrievePostgresConnectionInfo(postgresId: databaseId);
+    return internal ? info.internalConnectionString : info.externalConnectionString;
+  } finally {
+    render.close();
+  }
+}
+
+/// Turns a connection string into an [Endpoint].
+///
+/// `Connection.openFromUrl` exists, but it takes TLS from an `sslmode` query
+/// parameter that Render's strings do not carry, and Render's *internal*
+/// string has no port at all — `Uri.port` reports 0 for that, which is not a
+/// port. Both are handled here rather than left to chance.
+Endpoint endpointFor(String connectionString) {
+  final uri = Uri.parse(connectionString);
+  final userInfo = uri.userInfo.split(':');
+
+  return Endpoint(
+    host: uri.host,
+    port: uri.hasPort ? uri.port : 5432,
+    database: uri.pathSegments.isEmpty ? 'postgres' : uri.pathSegments.first,
+    username: userInfo.isNotEmpty ? Uri.decodeComponent(userInfo.first) : null,
+    password: userInfo.length > 1 ? Uri.decodeComponent(userInfo[1]) : null,
+  );
+}
+
+/// Opens a connection, with TLS.
+///
+/// Render requires TLS for external connections and supports it internally.
+/// [SslMode.require] encrypts without verifying the certificate chain, which
+/// is what Render's managed certificates need; [SslMode.verifyFull] would want
+/// a `securityContext` carrying their CA.
+Future<Connection> openConnection(String connectionString) => Connection.open(
+      endpointFor(connectionString),
+      settings: const ConnectionSettings(
+        sslMode: SslMode.require,
+        applicationName: 'render_postgres_example',
+        connectTimeout: Duration(seconds: 15),
+      ),
+    );
+
+/// Hides the password in a connection string, for printing.
+String describe(String connectionString) {
+  final uri = Uri.parse(connectionString);
+  final user = uri.userInfo.split(':').first;
+  final port = uri.hasPort ? uri.port : 5432;
+  return '$user@${uri.host}:$port${uri.path}';
+}

package/examples/postgres/seed/lib/src/schema.dart

@@ -0,0 +1,46 @@
+/// The table this example uses, and the rows it starts with.
+///
+/// Kept in one place deliberately: the workflow tasks only ever read and write
+/// this table, they never define it. One definition means the seeder is the
+/// single answer to "what shape is the data".
+library;
+
+/// Creating the table is idempotent, so seeding can be re-run at will —
+/// which matters because a free Render Postgres instance is deleted 30 days
+/// after it is created, and this is what makes it reproducible.
+const createWidgetsTable = '''
+create table if not exists widgets (
+  id          serial primary key,
+  sku         text not null unique,
+  name        text not null,
+  quantity    integer not null default 0,
+  price_cents integer not null,
+  updated_at  timestamptz not null default now()
+)
+''';
+
+/// Inserting is idempotent too: a re-run refreshes a row rather than failing
+/// on the unique sku, or quietly doubling the inventory.
+const upsertWidget = '''
+insert into widgets (sku, name, quantity, price_cents)
+values (@sku, @name, @quantity, @priceCents)
+on conflict (sku) do update set
+  name        = excluded.name,
+  quantity    = excluded.quantity,
+  price_cents = excluded.price_cents,
+  updated_at  = now()
+returning id, sku, name, quantity, price_cents, updated_at
+''';
+
+/// A small, boring inventory. Enough rows to make a `where` and an aggregate
+/// mean something, few enough to read in a terminal.
+const dummyWidgets = <Map<String, Object?>>[
+  {'sku': 'WDG-001', 'name': 'Hex bolt, M8', 'quantity': 500, 'priceCents': 12},
+  {'sku': 'WDG-002', 'name': 'Hex nut, M8', 'quantity': 480, 'priceCents': 7},
+  {'sku': 'WDG-003', 'name': 'Flat washer, M8', 'quantity': 1200, 'priceCents': 3},
+  {'sku': 'WDG-004', 'name': 'Socket cap screw, M6', 'quantity': 220, 'priceCents': 21},
+  {'sku': 'WDG-005', 'name': 'Ball bearing, 608', 'quantity': 64, 'priceCents': 145},
+  {'sku': 'WDG-006', 'name': 'Timing belt, 200mm', 'quantity': 18, 'priceCents': 890},
+  {'sku': 'WDG-007', 'name': 'Linear rail, 300mm', 'quantity': 6, 'priceCents': 2450},
+  {'sku': 'WDG-008', 'name': 'Stepper motor, NEMA 17', 'quantity': 12, 'priceCents': 1799},
+];

package/examples/postgres/seed/pubspec.yaml

@@ -0,0 +1,17 @@
+name: render_dart_postgres_seed
+description: Creates and fills the table the workflow tasks read.
+publish_to: none
+version: 0.1.0
+
+environment:
+  sdk: ^3.9.0
+
+dependencies:
+  postgres: ^3.5.12
+  # Fetches the connection string, so nothing secret lives in a file.
+  #
+  # A git dependency while render_api is unpublished; becomes a version
+  # constraint once it is on pub.dev.
+  render_api:
+    git:
+      url: https://github.com/timmaffett/render_api_sdk.git