libstore-c: Add C FFI for garbage collection with closure support

Adds nix_store_collect_garbage to perform flexible garbage collection
operations on the Nix store. Supports multiple GC modes including:
- Returning or deleting live/dead paths
- Closure-based deletion with safety checks respecting GC roots
- Optional ignoreLiveness flag for force deletion
- Per-operation byte limit

Includes:
- nix_gc_action enum with four action types
- Callback-based result iteration
- Support for local and closure-specific GC operations

This enables PR NixOS#8417-style closure-based GC through the C FFI.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: domenkozar

src/libstore-c/nix_api_store.cc

@@ -389,4 +389,82 @@ nix_err nix_store_compute_fs_closure(
     NIXC_CATCH_ERRS
 }
 
+nix_err nix_store_collect_garbage(
+    nix_c_context * context,
+    Store * store,
+    nix_gc_action action,
+    StorePath ** paths_to_delete,
+    size_t num_paths,
+    bool ignore_liveness,
+    uint64_t max_freed,
+    nix_store_path_callback callback,
+    void * user_data,
+    uint64_t * bytes_freed)
+{
+    if (context)
+        context->last_err_code = NIX_OK;
+    try {
+        if (!store)
+            return context ? context->last_err_code = NIX_ERR_KEY : NIX_ERR_KEY;
+
+        // Cast to GcStore
+        auto gcStore = dynamic_cast<nix::GcStore *>(&*store->ptr);
+        if (!gcStore)
+            throw nix::Unsupported("Store does not support garbage collection");
+
+        // Build GCOptions
+        nix::GCOptions options;
+
+        // Convert nix_gc_action to GCOptions::GCAction
+        switch (action) {
+            case NIX_GC_RETURN_LIVE:
+                options.action = nix::GCOptions::gcReturnLive;
+                break;
+            case NIX_GC_RETURN_DEAD:
+                options.action = nix::GCOptions::gcReturnDead;
+                break;
+            case NIX_GC_DELETE_DEAD:
+                options.action = nix::GCOptions::gcDeleteDead;
+                break;
+            case NIX_GC_DELETE_SPECIFIC:
+                options.action = nix::GCOptions::gcDeleteSpecific;
+                break;
+            default:
+                return context ? context->last_err_code = NIX_ERR_KEY : NIX_ERR_KEY;
+        }
+
+        options.ignoreLiveness = ignore_liveness;
+        options.maxFreed = max_freed;
+
+        // Add paths to delete if provided and action is DELETE_SPECIFIC
+        if (action == NIX_GC_DELETE_SPECIFIC && paths_to_delete && num_paths > 0) {
+            for (size_t i = 0; i < num_paths; i++) {
+                if (!paths_to_delete[i])
+                    return context ? context->last_err_code = NIX_ERR_KEY : NIX_ERR_KEY;
+                options.pathsToDelete.insert(paths_to_delete[i]->path);
+            }
+        }
+
+        // Run garbage collection
+        nix::GCResults results;
+        gcStore->collectGarbage(options, results);
+
+        // Invoke callback for each path in the results
+        if (callback) {
+            for (const auto & pathStr : results.paths) {
+                auto path = store->ptr->parseStorePath(pathStr);
+                StorePath sp{path};
+                callback(&sp, user_data);
+            }
+        }
+
+        // Return bytes freed if requested
+        if (bytes_freed)
+            *bytes_freed = results.bytesFreed;
+
+        return NIX_OK;
+    }
+    NIXC_CATCH_ERRS
+}
+
 } // extern "C"

src/libstore-c/nix_api_store.h

@@ -345,6 +345,22 @@ nix_err nix_store_add_indirect_root(nix_c_context * context, Store * store, cons
  */
 nix_err nix_store_delete_path(nix_c_context * context, Store * store, const char * path, uint64_t * bytes_freed);
 
+/**
+ * @brief Garbage collection action types
+ *
+ * Specifies what the garbage collection operation should do.
+ */
+typedef enum {
+    /** Return the set of live paths (reachable from roots) */
+    NIX_GC_RETURN_LIVE,
+    /** Return the set of dead paths (not reachable from roots) */
+    NIX_GC_RETURN_DEAD,
+    /** Delete all dead paths */
+    NIX_GC_DELETE_DEAD,
+    /** Delete only the specific paths provided (if they are dead) */
+    NIX_GC_DELETE_SPECIFIC,
+} nix_gc_action;
+
 /**
  * @brief Callback for iterating over store paths
  *
@@ -384,6 +400,49 @@ nix_err nix_store_compute_fs_closure(
     nix_store_path_callback callback,
     void * user_data);
 
+/**
+ * @brief Perform garbage collection on the store.
+ *
+ * This function provides flexible garbage collection with different modes:
+ * - NIX_GC_RETURN_LIVE: Returns paths reachable from GC roots (live paths)
+ * - NIX_GC_RETURN_DEAD: Returns paths not reachable from GC roots (dead paths)
+ * - NIX_GC_DELETE_DEAD: Deletes all dead paths
+ * - NIX_GC_DELETE_SPECIFIC: Deletes specific paths from the `paths_to_delete` array,
+ *   but only if they are not reachable from GC roots (respects liveness)
+ *
+ * When `ignore_liveness` is true, safety checks are bypassed (dangerous!).
+ *
+ * This only works with GcStore implementations (e.g., LocalStore).
+ *
+ * @param[out] context Optional, stores error information
+ * @param[in] store Nix Store reference (must support GC)
+ * @param[in] action The garbage collection action to perform
+ * @param[in] paths_to_delete For NIX_GC_DELETE_SPECIFIC: paths to consider for deletion.
+ *                             Can be NULL for other actions. Array is not modified.
+ * @param[in] num_paths Number of paths in paths_to_delete (0 if paths_to_delete is NULL)
+ * @param[in] ignore_liveness If true, ignore reachability from roots and delete even live paths.
+ *                            Only has effect with NIX_GC_DELETE_SPECIFIC. Dangerous!
+ * @param[in] max_freed Stop after freeing this many bytes. 0 means no limit.
+ * @param[in] callback Optional callback function called for each path in the result set
+ *                     (paths returned, deleted, or considered). Can be NULL.
+ * @param[in] user_data Arbitrary data passed to the callback
+ * @param[out] bytes_freed Optional pointer to uint64_t that will be set to the number of
+ *                         bytes freed (for delete operations) or would be freed (for return operations).
+ *                         Can be NULL if not needed.
+ * @return NIX_OK on success, error code on failure
+ */
+nix_err nix_store_collect_garbage(
+    nix_c_context * context,
+    Store * store,
+    nix_gc_action action,
+    StorePath ** paths_to_delete,
+    size_t num_paths,
+    bool ignore_liveness,
+    uint64_t max_freed,
+    nix_store_path_callback callback,
+    void * user_data,
+    uint64_t * bytes_freed);
+
 // cffi end
 #ifdef __cplusplus
 }