From d065a1a910d30ff8c07abe78482a73823383f650 Mon Sep 17 00:00:00 2001
From: lluisemper <58423269+lluisemper@users.noreply.github.com>
Date: Sat, 2 Aug 2025 20:28:23 +0200
Subject: [PATCH] src: add support for AbortSignal in backup method

This adds support for passing an AbortSignal to the database backup
function. If the signal is aborted during the backup process, the
operation is interrupted and a rejection is returned with an
AbortError.

The signal is optionally passed through the options object. Internally,
the signal is stored and periodically checked between backup steps to
respond quickly to abort requests.

This improves integration with modern web APIs and aligns with how
abortable operations are handled elsewhere in the Node.js ecosystem.

Fixes: https://github.com/nodejs/node/issues/58888
---
 doc/api/sqlite.md                         |  35 +++++
 lib/sqlite.js                             |  28 +++-
 src/env_properties.h                      |   2 +
 src/node_sqlite.cc                        | 165 ++++++++++++++++++++--
 test/parallel/test-sqlite-backup-abort.js | 109 ++++++++++++++
 5 files changed, 328 insertions(+), 11 deletions(-)
 create mode 100644 test/parallel/test-sqlite-backup-abort.js

diff --git a/doc/api/sqlite.md b/doc/api/sqlite.md
index cf4871734bdad6..8c9c52a45645ee 100644
--- a/doc/api/sqlite.md
+++ b/doc/api/sqlite.md
@@ -763,8 +763,10 @@ changes:
 -->
 
 * `sourceDb` {DatabaseSync} The database to backup. The source database must be open.
+
 * `path` {string | Buffer | URL} The path where the backup will be created. If the file already exists,
   the contents will be overwritten.
+
 * `options` {Object} Optional configuration for the backup. The
   following properties are supported:
   * `source` {string} Name of the source database. This can be `'main'` (the default primary database) or any other
@@ -774,6 +776,11 @@ changes:
   * `rate` {number} Number of pages to be transmitted in each batch of the backup. **Default:** `100`.
   * `progress` {Function} Callback function that will be called with the number of pages copied and the total number of
     pages.
+  * `signal` {AbortSignal} An optional AbortSignal that can be used to abort the backup operation.\
+    If the signal is aborted, the backup operation will be cancelled and the Promise will reject with an `AbortError`.\
+    **Note:** Aborting is a best-effort mechanism; the backup may complete before the abort is processed due to race
+    conditions.
+
 * Returns: {Promise} A promise that resolves when the backup is completed and rejects if an error occurs.
 
 This method makes a database backup. This method abstracts the [`sqlite3_backup_init()`][], [`sqlite3_backup_step()`][]
@@ -813,6 +820,34 @@ const totalPagesTransferred = await backup(sourceDb, 'backup.db', {
 console.log('Backup completed', totalPagesTransferred);
 ```
 
+### Aborting a backup
+
+The backup operation can be cancelled using an `AbortSignal`:
+
+```cjs
+const { backup, DatabaseSync } = require('node:sqlite');
+
+(async () => {
+  const sourceDb = new DatabaseSync('source.db');
+
+  try {
+    await backup(sourceDb, 'backup.db', {
+      signal: AbortSignal.timeout(5000),
+      progress: ({ totalPages, remainingPages }) => {
+        console.log('Backup in progress', { totalPages, remainingPages });
+      },
+    });
+    console.log('Backup completed successfully');
+  } catch (error) {
+    if (error.name === 'AbortError') {
+      console.log('Backup was cancelled:', error.message);
+    } else {
+      console.error('Backup failed:', error.message);
+    }
+  }
+})();
+```
+
 ## `sqlite.constants`
 
 <!-- YAML
diff --git a/lib/sqlite.js b/lib/sqlite.js
index 6d6ada72008f1c..19a4177506211d 100644
--- a/lib/sqlite.js
+++ b/lib/sqlite.js
@@ -1,6 +1,32 @@
 'use strict';
+const {
+  PromiseReject,
+} = primordials;
+const {
+  AbortError,
+} = require('internal/errors');
+const {
+  validateAbortSignal,
+  validateObject,
+  validateString,
+} = require('internal/validators');
 const { emitExperimentalWarning } = require('internal/util');
 
 emitExperimentalWarning('SQLite');
 
-module.exports = internalBinding('sqlite');
+const binding = internalBinding('sqlite');
+
+function backup(sourceDb, path, options = {}) {
+  validateObject(sourceDb, 'sourceDb');
+  validateString(path, 'options.headers.host');
+  validateAbortSignal(options.signal, 'options.signal');
+  if (options.signal?.aborted) {
+    return PromiseReject(new AbortError(undefined, { cause: options.signal.reason }));
+  }
+  return binding.backup(sourceDb, path, options);
+}
+
+module.exports = {
+  ...binding,
+  backup,
+};
diff --git a/src/env_properties.h b/src/env_properties.h
index 251effe95c5071..a02798ef0f6d7b 100644
--- a/src/env_properties.h
+++ b/src/env_properties.h
@@ -332,6 +332,8 @@
   V(readable_string, "readable")                                               \
   V(read_bigints_string, "readBigInts")                                        \
   V(reason_string, "reason")                                                   \
+  V(cause_string, "cause")                                                     \
+  V(aborted_string, "aborted")                                                 \
   V(refresh_string, "refresh")                                                 \
   V(regexp_string, "regexp")                                                   \
   V(remaining_pages_string, "remainingPages")                                  \
diff --git a/src/node_sqlite.cc b/src/node_sqlite.cc
index 3a7c39e72cf421..680afaab9781e0 100644
--- a/src/node_sqlite.cc
+++ b/src/node_sqlite.cc
@@ -12,6 +12,7 @@
 #include "threadpoolwork-inl.h"
 #include "util-inl.h"
 
+#include <atomic>
 #include <cinttypes>
 
 namespace node {
@@ -115,13 +116,67 @@ using v8::Value;
         UNREACHABLE("Bad SQLite value");                                       \
     }                                                                          \
   } while (0)
+// TODO(@lluisemper) This is a copy of node::AbortError, use js native
+// AbortError constructor to allow instanceof checks in JS.
+class AbortError {
+ public:
+  static MaybeLocal<Object> New(
+      Isolate* isolate,
+      std::string_view message = "The operation was aborted",
+      Local<Value> cause = Local<Value>()) {
+    Local<String> js_msg;
+    Local<Object> error_obj;
+    Local<Context> context = isolate->GetCurrentContext();
+    Environment* env = Environment::GetCurrent(isolate);
+
+    if (!String::NewFromUtf8(isolate,
+                             message.data(),
+                             NewStringType::kNormal,
+                             static_cast<int>(message.size()))
+             .ToLocal(&js_msg) ||
+        !Exception::Error(js_msg)->ToObject(context).ToLocal(&error_obj)) {
+      return MaybeLocal<Object>();
+    }
+
+    Local<String> error_name;
+    if (!String::NewFromUtf8(isolate, "AbortError").ToLocal(&error_name)) {
+      return MaybeLocal<Object>();
+    }
+    if (error_obj->Set(context, env->name_string(), error_name).IsNothing()) {
+      return MaybeLocal<Object>();
+    }
+
+    Local<String> code_key;
+    Local<String> code_value;
+    if (!String::NewFromUtf8(isolate, "code").ToLocal(&code_key) ||
+        !String::NewFromUtf8(isolate, "ABORT_ERR").ToLocal(&code_value)) {
+      return MaybeLocal<Object>();
+    }
+    if (error_obj->Set(context, code_key, code_value).IsNothing()) {
+      return MaybeLocal<Object>();
+    }
+
+    if (!cause.IsEmpty() && !cause->IsUndefined()) {
+      if (error_obj->Set(context, env->cause_string(), cause).IsNothing()) {
+        return MaybeLocal<Object>();
+      }
+    }
+
+    return error_obj;
+  }
+};
 
 inline MaybeLocal<Object> CreateSQLiteError(Isolate* isolate,
-                                            const char* message) {
+                                            std::string_view message) {
   Local<String> js_msg;
   Local<Object> e;
   Environment* env = Environment::GetCurrent(isolate);
-  if (!String::NewFromUtf8(isolate, message).ToLocal(&js_msg) ||
+
+  if (!String::NewFromUtf8(isolate,
+                           message.data(),
+                           NewStringType::kNormal,
+                           static_cast<int>(message.size()))
+           .ToLocal(&js_msg) ||
       !Exception::Error(js_msg)
            ->ToObject(isolate->GetCurrentContext())
            .ToLocal(&e) ||
@@ -131,6 +186,7 @@ inline MaybeLocal<Object> CreateSQLiteError(Isolate* isolate,
           .IsNothing()) {
     return MaybeLocal<Object>();
   }
+
   return e;
 }
 
@@ -433,16 +489,21 @@ class BackupJob : public ThreadPoolWork {
                      std::string destination_name,
                      std::string dest_db,
                      int pages,
-                     Local<Function> progressFunc)
+                     Local<Function> progress_func,
+                     Local<Object> abort_signal = Local<Object>())
       : ThreadPoolWork(env, "node_sqlite3.BackupJob"),
         env_(env),
         source_(source),
         pages_(pages),
         source_db_(std::move(source_db)),
         destination_name_(std::move(destination_name)),
-        dest_db_(std::move(dest_db)) {
+        dest_db_(std::move(dest_db)),
+        is_aborted_(false) {
     resolver_.Reset(env->isolate(), resolver);
-    progressFunc_.Reset(env->isolate(), progressFunc);
+    progress_func_.Reset(env->isolate(), progress_func);
+    if (!abort_signal.IsEmpty()) {
+      abort_signal_.Reset(env->isolate(), abort_signal);
+    }
   }
 
   void ScheduleBackup() {
@@ -471,6 +532,10 @@ class BackupJob : public ThreadPoolWork {
   }
 
   void DoThreadPoolWork() override {
+    if (is_aborted_.load(std::memory_order_acquire)) {
+      backup_status_ = SQLITE_INTERRUPT;
+      return;
+    }
     backup_status_ = sqlite3_backup_step(backup_, pages_);
   }
 
@@ -479,6 +544,12 @@ class BackupJob : public ThreadPoolWork {
     Local<Promise::Resolver> resolver =
         Local<Promise::Resolver>::New(env()->isolate(), resolver_);
 
+    if (is_aborted_.load(std::memory_order_acquire) ||
+        backup_status_ == SQLITE_INTERRUPT) {
+      HandleAbortError(resolver);
+      return;
+    }
+
     if (!(backup_status_ == SQLITE_OK || backup_status_ == SQLITE_DONE ||
           backup_status_ == SQLITE_BUSY || backup_status_ == SQLITE_LOCKED)) {
       HandleBackupError(resolver, backup_status_);
@@ -489,7 +560,7 @@ class BackupJob : public ThreadPoolWork {
     int remaining_pages = sqlite3_backup_remaining(backup_);
     if (remaining_pages != 0) {
       Local<Function> fn =
-          Local<Function>::New(env()->isolate(), progressFunc_);
+          Local<Function>::New(env()->isolate(), progress_func_);
       if (!fn.IsEmpty()) {
         Local<Object> progress_info = Object::New(env()->isolate());
         if (progress_info
@@ -515,6 +586,14 @@ class BackupJob : public ThreadPoolWork {
           return;
         }
       }
+      if (CheckAbortSignal()) {
+        // TODO(@lluisemper): BackupJob does not implement proper async context
+        //  tracking yet.
+        // Consider inheriting from AsyncWrap and using CallbackScope to
+        // propagate async context, similar to other ThreadPoolWork items.
+        HandleAbortError(resolver);
+        return;
+      }
 
       // There's still work to do
       this->ScheduleWork();
@@ -548,6 +627,10 @@ class BackupJob : public ThreadPoolWork {
       sqlite3_close_v2(dest_);
       dest_ = nullptr;
     }
+
+    if (!abort_signal_.IsEmpty()) {
+      abort_signal_.Reset();
+    }
   }
 
  private:
@@ -573,12 +656,65 @@ class BackupJob : public ThreadPoolWork {
     resolver->Reject(env()->context(), e).ToChecked();
   }
 
+  inline MaybeLocal<Object> CreateAbortError(
+      Isolate* isolate,
+      std::string_view message = "The operation was aborted") {
+    Environment* env = Environment::GetCurrent(isolate);
+    HandleScope scope(isolate);
+    Local<Value> cause;
+
+    if (!abort_signal_.IsEmpty()) {
+      Local<Object> signal = abort_signal_.Get(isolate);
+      Local<String> reason_key = env->reason_string();
+
+      if (!signal->Get(isolate->GetCurrentContext(), reason_key)
+               .ToLocal(&cause)) {
+        cause = Local<Value>();
+      }
+    }
+
+    return AbortError::New(isolate, message, cause);
+  }
+
+  void HandleAbortError(Local<Promise::Resolver> resolver) {
+    Local<Object> e;
+    if (!CreateAbortError(env()->isolate()).ToLocal(&e)) {
+      Finalize();
+      return;
+    }
+
+    Finalize();
+    resolver->Reject(env()->context(), e).ToChecked();
+  }
+
+  bool CheckAbortSignal() {
+    if (abort_signal_.IsEmpty()) {
+      return false;
+    }
+
+    Isolate* isolate = env()->isolate();
+    HandleScope scope(isolate);
+    Local<Object> signal = abort_signal_.Get(isolate);
+
+    Local<Value> aborted_value;
+    if (signal->Get(env()->context(), env()->aborted_string())
+            .ToLocal(&aborted_value)) {
+      if (aborted_value->BooleanValue(isolate)) {
+        is_aborted_.store(true, std::memory_order_release);
+        return true;
+      }
+    }
+
+    return false;
+  }
+
   Environment* env() const { return env_; }
 
   Environment* env_;
   DatabaseSync* source_;
   Global<Promise::Resolver> resolver_;
-  Global<Function> progressFunc_;
+  Global<Function> progress_func_;
+  Global<Object> abort_signal_;
   sqlite3* dest_ = nullptr;
   sqlite3_backup* backup_ = nullptr;
   int pages_;
@@ -586,6 +722,7 @@ class BackupJob : public ThreadPoolWork {
   std::string source_db_;
   std::string destination_name_;
   std::string dest_db_;
+  std::atomic<bool> is_aborted_;
 };
 
 UserDefinedFunction::UserDefinedFunction(Environment* env,
@@ -1538,7 +1675,8 @@ void Backup(const FunctionCallbackInfo<Value>& args) {
   int rate = 100;
   std::string source_db = "main";
   std::string dest_db = "main";
-  Local<Function> progressFunc = Local<Function>();
+  Local<Function> progress_func = Local<Function>();
+  Local<Object> abort_signal = Local<Object>();
 
   if (args.Length() > 2) {
     if (!args[2]->IsObject()) {
@@ -1610,7 +1748,13 @@ void Backup(const FunctionCallbackInfo<Value>& args) {
             "The \"options.progress\" argument must be a function.");
         return;
       }
-      progressFunc = progress_v.As<Function>();
+      progress_func = progress_v.As<Function>();
+    }
+
+    Local<Value> signal_v;
+    if (!options->Get(env->context(), env->signal_string())
+             .ToLocal(&signal_v)) {
+      return;
     }
   }
 
@@ -1627,7 +1771,8 @@ void Backup(const FunctionCallbackInfo<Value>& args) {
                                  dest_path.value(),
                                  std::move(dest_db),
                                  rate,
-                                 progressFunc);
+                                 progress_func,
+                                 abort_signal);
   db->AddBackup(job);
   job->ScheduleBackup();
 }
diff --git a/test/parallel/test-sqlite-backup-abort.js b/test/parallel/test-sqlite-backup-abort.js
new file mode 100644
index 00000000000000..fa63577cb9b816
--- /dev/null
+++ b/test/parallel/test-sqlite-backup-abort.js
@@ -0,0 +1,109 @@
+'use strict';
+const { skipIfSQLiteMissing } = require('../common');
+skipIfSQLiteMissing();
+const tmpdir = require('../common/tmpdir');
+const { join } = require('node:path');
+const { DatabaseSync, backup } = require('node:sqlite');
+const { test } = require('node:test');
+const assert = require('node:assert');
+let cnt = 0;
+
+tmpdir.refresh();
+
+function nextDb() {
+  return join(tmpdir.path, `database-${cnt++}.db`);
+}
+
+test('backup with AbortSignal - abort during operation', async (t) => {
+  const sourceDbPath = nextDb();
+  const destDbPath = nextDb();
+
+  const sourceDb = new DatabaseSync(sourceDbPath);
+  t.after(() => { sourceDb.close(); });
+
+  // Create a larger table to make backup take longer
+  sourceDb.exec(`
+    CREATE TABLE test_table (id INTEGER PRIMARY KEY, data TEXT);
+  `);
+
+  const stmt = sourceDb.prepare('INSERT INTO test_table (data) VALUES (?)');
+  for (let i = 0; i < 10000; i++) {
+    stmt.run(`Test data ${i}`);
+  }
+
+  try {
+    await backup(sourceDb, destDbPath, {
+      signal: AbortSignal.timeout(10),
+      rate: 1 // Very slow to increase chance of abort
+    });
+
+    // If we get here, the backup completed before abort
+    // This is acceptable - the backup might finish before abort triggers
+  } catch (error) {
+    assert.strictEqual(error.name, 'AbortError');
+    assert.strictEqual(error.cause, 'Test cancellation');
+  }
+});
+
+test('backup with AbortSignal - pre-aborted signal', async (t) => {
+  const sourceDbPath = nextDb();
+  const destDbPath = nextDb();
+
+  const sourceDb = new DatabaseSync(sourceDbPath);
+  t.after(() => { sourceDb.close(); });
+
+  sourceDb.exec(`
+    CREATE TABLE test_table (id INTEGER PRIMARY KEY, data TEXT);
+    INSERT INTO test_table (data) VALUES ('test');
+  `);
+
+  const signal = AbortSignal.abort('Already aborted');
+
+  await assert.rejects(
+    backup(sourceDb, destDbPath, { signal }),
+    {
+      name: 'AbortError',
+      cause: 'Already aborted'
+    }
+  );
+});
+
+test('backup with AbortSignal - invalid signal type', (t) => {
+  const sourceDbPath = nextDb();
+  const destDbPath = nextDb();
+
+  const sourceDb = new DatabaseSync(sourceDbPath);
+  t.after(() => { sourceDb.close(); });
+
+  sourceDb.exec(`
+    CREATE TABLE test_table (id INTEGER PRIMARY KEY, data TEXT);
+  `);
+
+  assert.throws(
+    () => backup(sourceDb, destDbPath, { signal: 'not-a-signal' }),
+    {
+      code: 'ERR_INVALID_ARG_TYPE',
+      message: `The "options.signal" property must be an instance of AbortSignal. Received type string ('not-a-signal')`
+    }
+  );
+});
+
+test('backup with AbortSignal - empty object as signal', (t) => {
+  const sourceDbPath = nextDb();
+  const destDbPath = nextDb();
+
+  const sourceDb = new DatabaseSync(sourceDbPath);
+  t.after(() => { sourceDb.close(); });
+
+  sourceDb.exec(`
+    CREATE TABLE test_table (id INTEGER PRIMARY KEY, data TEXT);
+  `);
+
+  assert.throws(
+    () => backup(sourceDb, destDbPath, { signal: {} }),
+    {
+      code: 'ERR_INVALID_ARG_TYPE',
+      message: 'The "options.signal" property must be an instance of AbortSignal. Received an instance of Object'
+    }
+  );
+});