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: #58888

Author: lluisemper

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

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,
+};

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")                                  \

src/node_sqlite.cc

@@ -12,6 +12,7 @@
 #include "threadpoolwork-inl.h"
 #include "util-inl.h"
 
+#include <atomic>
 #include <cinttypes>
 
 namespace node {
@@ -116,12 +117,65 @@ using v8::Value;
     }                                                                          \
   } while (0)
 
+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 +185,7 @@ inline MaybeLocal<Object> CreateSQLiteError(Isolate* isolate,
           .IsNothing()) {
     return MaybeLocal<Object>();
   }
+
   return e;
 }
 
@@ -433,16 +488,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 +531,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 +543,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 +559,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 +585,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 +626,10 @@ class BackupJob : public ThreadPoolWork {
       sqlite3_close_v2(dest_);
       dest_ = nullptr;
     }
+
+    if (!abort_signal_.IsEmpty()) {
+      abort_signal_.Reset();
+    }
   }
 
  private:
@@ -573,19 +655,73 @@ 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_;
   int backup_status_ = SQLITE_OK;
   std::string source_db_;
   std::string destination_name_;
   std::string dest_db_;
+  std::atomic<bool> is_aborted_;
 };
 
 UserDefinedFunction::UserDefinedFunction(Environment* env,
@@ -1538,7 +1674,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 +1747,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 +1770,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();
 }