feat(node): core SDK — napi crate, TS Queue/Worker, serializers, CLI

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/taskito-core", "crates/taskito-python", "crates/taskito-workflows", "crates/taskito-mesh"]
+members = ["crates/taskito-core", "crates/taskito-python", "crates/taskito-node", "crates/taskito-workflows", "crates/taskito-mesh"]
 resolver = "2"
 
 [workspace.dependencies]

crates/taskito-node/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "taskito-node"
+version = "0.16.3"
+edition = "2021"
+description = "Node.js (napi-rs) bindings for the Taskito task-queue core"
+license = "MIT"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[features]
+default = []
+postgres = ["taskito-core/postgres"]
+redis = ["taskito-core/redis"]
+
+[dependencies]
+taskito-core = { path = "../taskito-core" }
+napi = { version = "2", default-features = false, features = ["napi8", "tokio_rt"] }
+napi-derive = "2"
+tokio = { workspace = true }
+crossbeam-channel = { workspace = true }
+async-trait = { workspace = true }
+log = { workspace = true }
+
+[build-dependencies]
+napi-build = "2"

crates/taskito-node/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    napi_build::setup();
+}

crates/taskito-node/src/backend.rs

@@ -0,0 +1,57 @@
+//! Feature-gated construction of a [`StorageBackend`] from JS [`OpenOptions`].
+
+use napi::bindgen_prelude::{Error, Result, Status};
+use taskito_core::{SqliteStorage, StorageBackend};
+
+use crate::config::OpenOptions;
+use crate::error::{invalid_arg, to_napi_err};
+
+const DEFAULT_SQLITE_POOL: u32 = 8;
+#[cfg(feature = "postgres")]
+const DEFAULT_POSTGRES_POOL: u32 = 10;
+#[cfg(feature = "postgres")]
+const DEFAULT_POSTGRES_SCHEMA: &str = "taskito";
+
+/// Resolve a connection pool size, rejecting an explicit zero — r2d2 requires
+/// `max_size > 0` and panics otherwise, which would crash the whole process.
+fn resolve_pool_size(pool_size: Option<u32>, default: u32) -> Result<u32> {
+    match pool_size {
+        Some(0) => Err(invalid_arg("poolSize must be greater than 0")),
+        Some(n) => Ok(n),
+        None => Ok(default),
+    }
+}
+
+/// Open the storage backend named by `options.backend` (default `"sqlite"`).
+/// Returns an error if a requested backend was not compiled into this addon.
+pub fn open(options: &OpenOptions) -> Result<StorageBackend> {
+    match options.backend.as_deref().unwrap_or("sqlite") {
+        "sqlite" => {
+            let pool = resolve_pool_size(options.pool_size, DEFAULT_SQLITE_POOL)?;
+            let storage = SqliteStorage::with_pool_size(&options.dsn, pool).map_err(to_napi_err)?;
+            Ok(StorageBackend::Sqlite(storage))
+        }
+        #[cfg(feature = "postgres")]
+        "postgres" => {
+            let schema = options.schema.as_deref().unwrap_or(DEFAULT_POSTGRES_SCHEMA);
+            let pool = resolve_pool_size(options.pool_size, DEFAULT_POSTGRES_POOL)?;
+            let storage =
+                taskito_core::PostgresStorage::with_schema_and_pool_size(&options.dsn, schema, pool)
+                    .map_err(to_napi_err)?;
+            Ok(StorageBackend::Postgres(storage))
+        }
+        #[cfg(feature = "redis")]
+        "redis" => {
+            let storage = match options.prefix.as_deref() {
+                Some(prefix) => taskito_core::RedisStorage::with_prefix(&options.dsn, prefix),
+                None => taskito_core::RedisStorage::new(&options.dsn),
+            }
+            .map_err(to_napi_err)?;
+            Ok(StorageBackend::Redis(storage))
+        }
+        other => Err(Error::new(
+            Status::InvalidArg,
+            format!("backend '{other}' is not available (not a known backend, or this addon was built without its cargo feature)"),
+        )),
+    }
+}

crates/taskito-node/src/config.rs

@@ -0,0 +1,86 @@
+//! Plain option objects passed from JavaScript. napi maps snake_case Rust
+//! fields to camelCase JS keys (`maxRetries`, `timeoutMs`).
+
+use napi_derive::napi;
+
+/// How to open a queue's storage backend.
+#[napi(object)]
+pub struct OpenOptions {
+    /// `"sqlite"` (default), `"postgres"`, or `"redis"`. The latter two require
+    /// the addon to be built with the matching cargo feature.
+    pub backend: Option<String>,
+    /// SQLite file path, Postgres URL, or Redis URL.
+    pub dsn: String,
+    /// Connection pool size (SQLite/Postgres).
+    pub pool_size: Option<u32>,
+    /// Postgres schema (default `"taskito"`).
+    pub schema: Option<String>,
+    /// Redis key prefix.
+    pub prefix: Option<String>,
+    /// Optional namespace applied to enqueued jobs and the worker scheduler.
+    pub namespace: Option<String>,
+}
+
+/// Per-enqueue overrides. All optional — omitted fields fall back to defaults
+/// in [`crate::convert::build_new_job`].
+#[napi(object)]
+#[derive(Default)]
+pub struct EnqueueOptions {
+    pub queue: Option<String>,
+    pub priority: Option<i32>,
+    pub max_retries: Option<i32>,
+    pub timeout_ms: Option<i64>,
+    /// Run no earlier than `now + delayMs` (delayed/scheduled job).
+    pub delay_ms: Option<i64>,
+    /// Dedup key — a second enqueue with the same key is a no-op while the
+    /// first is pending/running (idempotency).
+    pub unique_key: Option<String>,
+    /// Free-form metadata string stored with the job.
+    pub metadata: Option<String>,
+    /// Namespace override for this job.
+    pub namespace: Option<String>,
+}
+
+/// Filter for [`crate::queue::JsQueue::list_jobs`]. All fields optional.
+#[napi(object)]
+#[derive(Default)]
+pub struct JobFilter {
+    /// Lowercase status (`"pending"`, `"running"`, `"complete"`, `"failed"`, `"dead"`, `"cancelled"`).
+    pub status: Option<String>,
+    pub queue: Option<String>,
+    pub task: Option<String>,
+    pub limit: Option<i64>,
+    pub offset: Option<i64>,
+}
+
+/// Per-task configuration registered on the scheduler before the worker runs.
+#[napi(object)]
+pub struct TaskConfigInput {
+    pub name: String,
+    pub max_retries: Option<i32>,
+    pub retry_base_delay_ms: Option<i64>,
+    pub retry_max_delay_ms: Option<i64>,
+    pub max_concurrent: Option<i32>,
+    /// Rate-limit spec like `"100/m"`, `"50/s"`, `"3600/h"`.
+    pub rate_limit: Option<String>,
+}
+
+/// Per-queue configuration registered on the scheduler before the worker runs.
+#[napi(object)]
+pub struct QueueConfigInput {
+    pub name: String,
+    pub max_concurrent: Option<i32>,
+    pub rate_limit: Option<String>,
+}
+
+/// Options for a running worker. `queues` defaults to `["default"]`.
+#[napi(object)]
+#[derive(Default)]
+pub struct WorkerOptions {
+    pub queues: Option<Vec<String>>,
+    pub channel_capacity: Option<u32>,
+    /// Jobs claimed per scheduler poll (default 1).
+    pub batch_size: Option<u32>,
+    pub task_configs: Option<Vec<TaskConfigInput>>,
+    pub queue_configs: Option<Vec<QueueConfigInput>>,
+}

crates/taskito-node/src/convert/job.rs

@@ -0,0 +1,99 @@
+//! Marshalling between core job types and JS-facing shapes. Kept out of the
+//! logic modules so `queue`/`worker` read as intent, not plumbing.
+
+use napi::bindgen_prelude::{Buffer, Result};
+use napi_derive::napi;
+use taskito_core::job::now_millis;
+use taskito_core::{Job, NewJob};
+
+use crate::config::EnqueueOptions;
+use crate::error::non_negative;
+
+const DEFAULT_QUEUE: &str = "default";
+const DEFAULT_MAX_RETRIES: i32 = 3;
+const DEFAULT_TIMEOUT_MS: i64 = 300_000;
+
+/// Build a [`NewJob`] from a task name, opaque payload bytes, and JS options.
+/// The core never interprets `payload` — the shell owns (de)serialization.
+/// `queue_namespace` is the queue-level default applied when the enqueue call
+/// doesn't override it.
+pub fn build_new_job(
+    task_name: String,
+    payload: Vec<u8>,
+    opts: EnqueueOptions,
+    queue_namespace: Option<&str>,
+) -> Result<NewJob> {
+    // Signed types reach us from JS; reject the negatives that would silently
+    // corrupt scheduling (premature timeout, retries disabled, past schedule).
+    let delay = non_negative(opts.delay_ms.unwrap_or(0), "delayMs")?;
+    let max_retries = match opts.max_retries {
+        Some(n) => non_negative(n as i64, "maxRetries")? as i32,
+        None => DEFAULT_MAX_RETRIES,
+    };
+    let timeout_ms = match opts.timeout_ms {
+        Some(n) => non_negative(n, "timeoutMs")?,
+        None => DEFAULT_TIMEOUT_MS,
+    };
+    Ok(NewJob {
+        queue: opts.queue.unwrap_or_else(|| DEFAULT_QUEUE.to_string()),
+        task_name,
+        payload,
+        priority: opts.priority.unwrap_or(0),
+        // Saturate so an extreme delay can't overflow into a past schedule.
+        scheduled_at: now_millis().saturating_add(delay),
+        max_retries,
+        timeout_ms,
+        unique_key: opts.unique_key,
+        metadata: opts.metadata,
+        notes: None,
+        depends_on: Vec::new(),
+        expires_at: None,
+        result_ttl_ms: None,
+        namespace: opts
+            .namespace
+            .or_else(|| queue_namespace.map(str::to_string)),
+    })
+}
+
+/// Passed to the JS task callback for each dispatched job. `payload` is the
+/// opaque arg blob the shell deserializes before running the task.
+#[napi(object)]
+pub struct JsTaskInvocation {
+    pub id: String,
+    pub task_name: String,
+    pub payload: Buffer,
+}
+
+/// JS-facing view of a stored [`Job`]. `result` is the opaque result blob (or
+/// `null`); the shell deserializes it.
+#[napi(object)]
+pub struct JsJob {
+    pub id: String,
+    pub queue: String,
+    pub task_name: String,
+    pub status: String,
+    pub priority: i32,
+    pub retry_count: i32,
+    pub max_retries: i32,
+    pub result: Option<Buffer>,
+    pub error: Option<String>,
+    pub created_at: i64,
+    pub completed_at: Option<i64>,
+}
+
+/// Convert a core [`Job`] into its JS-facing shape.
+pub fn job_to_js(job: Job) -> JsJob {
+    JsJob {
+        id: job.id,
+        queue: job.queue,
+        task_name: job.task_name,
+        status: job.status.as_str().to_string(),
+        priority: job.priority,
+        retry_count: job.retry_count,
+        max_retries: job.max_retries,
+        result: job.result.map(Buffer::from),
+        error: job.error,
+        created_at: job.created_at,
+        completed_at: job.completed_at,
+    }
+}

crates/taskito-node/src/convert/mod.rs

@@ -0,0 +1,13 @@
+//! Marshalling between core types and JS-facing shapes. One submodule per
+//! concern; kept out of the logic modules so they read as intent, not plumbing.
+
+mod job;
+mod stats;
+mod task_config;
+
+pub use job::{build_new_job, job_to_js, JsJob, JsTaskInvocation};
+pub use stats::{
+    dead_job_to_js, job_error_to_js, metric_to_js, stats_to_js, status_code, JsDeadJob, JsJobError,
+    JsMetric, JsStats,
+};
+pub use task_config::{queue_config, task_config};