libstore-c: Add new derivation and store path functions

Add several new functions to the C API:

StorePath operations:
- nix_store_path_hash: Extract the hash part from a store path
- nix_store_create_from_parts: Construct a store path from hash and name

Derivation operations:
- nix_derivation_clone: Clone a derivation
- nix_derivation_to_json: Serialize a derivation to JSON

Store operations:
- nix_store_drv_from_store_path: Load a derivation from a store path

Test the new functions, and improve documentation of some existing
functions to better distinguish them, also.

Co-authored-by: Tristan Ross <tristan.ross@determinate.systems>
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>

src/libstore-c/nix_api_store.cc

@@ -1,3 +1,6 @@
+#include <cstring>
+#include <span>
+
 #include "nix_api_store.h"
 #include "nix_api_store_internal.h"
 #include "nix_api_util.h"
@@ -8,6 +11,7 @@
 #include "nix/store/store-open.hh"
 #include "nix/store/build-result.hh"
 #include "nix/store/local-fs-store.hh"
+#include "nix/util/base-nix-32.hh"
 
 #include "nix/store/globals.hh"
 
@@ -222,6 +226,60 @@ StorePath * nix_store_path_clone(const StorePath * p)
     }
 }
 
+} // extern "C"
+
+template<size_t S>
+static auto to_cpp_array(const uint8_t (&r)[S])
+{
+    return reinterpret_cast<const std::array<std::byte, S> &>(r);
+}
+
+extern "C" {
+
+nix_err
+nix_store_path_hash(nix_c_context * context, const StorePath * store_path, nix_store_path_hash_part * hash_part_out)
+{
+    try {
+        auto hashPart = store_path->path.hashPart();
+        // Decode from Nix32 (base32) encoding to raw bytes
+        auto decoded = nix::BaseNix32::decode(hashPart);
+
+        assert(decoded.size() == sizeof(hash_part_out->bytes));
+        std::memcpy(hash_part_out->bytes, decoded.data(), sizeof(hash_part_out->bytes));
+        return NIX_OK;
+    }
+    NIXC_CATCH_ERRS
+}
+
+StorePath * nix_store_create_from_parts(
+    nix_c_context * context, const nix_store_path_hash_part * hash, const char * name, size_t name_len)
+{
+    if (context)
+        context->last_err_code = NIX_OK;
+    try {
+        // Encode the 20 raw bytes to Nix32 (base32) format
+        auto hashStr = nix::BaseNix32::encode(std::span<const std::byte>{to_cpp_array(hash->bytes)});
+
+        // Construct the store path basename: <hash>-<name>
+        std::string baseName;
+        baseName += hashStr;
+        baseName += "-";
+        baseName += std::string_view{name, name_len};
+
+        return new StorePath{nix::StorePath(std::move(baseName))};
+    }
+    NIXC_CATCH_ERRS_NULL
+}
+
+nix_derivation * nix_derivation_clone(const nix_derivation * d)
+{
+    try {
+        return new nix_derivation{d->drv};
+    } catch (...) {
+        return nullptr;
+    }
+}
+
 nix_derivation * nix_derivation_from_json(nix_c_context * context, Store * store, const char * json)
 {
     if (context)
@@ -232,6 +290,20 @@ nix_derivation * nix_derivation_from_json(nix_c_context * context, Store * store
     NIXC_CATCH_ERRS_NULL
 }
 
+nix_err nix_derivation_to_json(
+    nix_c_context * context, const nix_derivation * drv, nix_get_string_callback callback, void * userdata)
+{
+    if (context)
+        context->last_err_code = NIX_OK;
+    try {
+        auto result = static_cast<nlohmann::json>(drv->drv).dump();
+        if (callback) {
+            callback(result.data(), result.size(), userdata);
+        }
+    }
+    NIXC_CATCH_ERRS
+}
+
 StorePath * nix_add_derivation(nix_c_context * context, Store * store, nix_derivation * derivation)
 {
     if (context)
@@ -256,4 +328,14 @@ nix_err nix_store_copy_closure(nix_c_context * context, Store * srcStore, Store
     NIXC_CATCH_ERRS
 }
 
+nix_derivation * nix_store_drv_from_store_path(nix_c_context * context, Store * store, const StorePath * path)
+{
+    if (context)
+        context->last_err_code = NIX_OK;
+    try {
+        return new nix_derivation{store->ptr->derivationFromPath(path->path)};
+    }
+    NIXC_CATCH_ERRS_NULL
+}
+
 } // extern "C"