Home /Modules/advantage/acquire.h

acquire.h

advantage/transport/acquire.h · 90 line(s) · c

// acquire.h - Idempotent, content-addressed acquisition facade.
//
// One entry point for reaching remote resources over the supported secure
// protocols (https, http, sftp, ssh, file) and bringing their bytes into a
// local content-addressed store (CAS).
//
// Idempotency model:
//   * Downloaded bytes are stored under objects/<sha256>. The same content
//     always lands at the same path, so re-fetching is a no-op copy.
//   * Writes are atomic (temp file + rename), so an interrupted fetch never
//     corrupts the store.
//   * review() fetches only metadata (HTTP HEAD) without downloading a body.
//   * A fetch that has already been satisfied (object present) short-circuits
//     and is reported as `fromCache = true`.
//
// Security model:
//   * HTTPS verifies the certificate chain and hostname by default.
//   * SSH/SFTP enforce host-key checking via OpenSSH.
//   * Optional expectedSha256 lets a caller pin content; a mismatch fails
//     the fetch and discards the bytes.
#ifndef ADVANTAGE_ACQUIRE_H
#define ADVANTAGE_ACQUIRE_H

#include <cstdint>
#include <map>
#include <string>
#include <vector>

#include "http_client.h"
#include "sftp_client.h"

namespace advantage {

struct AcquireOptions {
    HttpOptions http;
    SftpOptions sftp;
    std::string expectedSha256;   // optional content pin (lowercase hex)
};

struct AcquireResult {
    bool        ok = false;
    bool        fromCache = false;   // object already present, no transfer
    std::string sha256;              // content id of the stored object
    std::string objectPath;          // absolute path in the CAS
    size_t      size = 0;
    int         httpStatus = 0;      // for http(s); 0 otherwise
    std::map<std::string, std::string> metadata;  // review() headers, etc.
    std::string error;               // populated when !ok
};

// A content-addressed store rooted at a directory. Thread-compatible (not
// internally synchronized); construct one per logical operation or guard
// externally.
class AcquisitionStore {
public:
    // Root directory for the CAS. Created (with an objects/ subdir) on demand.
    explicit AcquisitionStore(std::string root) : root_(std::move(root)) {}

    // Metadata-only "review": HTTP(S) HEAD. For non-HTTP schemes, reports
    // what can be known without transferring the body.
    AcquireResult review(const std::string &url, const AcquireOptions &opts = {});

    // "Obtain / download / store": fetch the resource and place it in the CAS.
    // Idempotent: returns fromCache=true if the content (by expectedSha256)
    // or a prior fetch of the same URL already satisfied this.
    AcquireResult fetch(const std::string &url, const AcquireOptions &opts = {});

    // Path where an object with the given content id lives (may not exist).
    std::string objectPathFor(const std::string &sha256) const;

    // True if an object with this content id is already stored.
    bool has(const std::string &sha256) const;

    const std::string &root() const { return root_; }

private:
    bool ensureLayout(std::string &err);
    // Store raw bytes into the CAS atomically; returns the object's sha256.
    AcquireResult commitBytes(const std::vector<uint8_t> &bytes,
                              const std::string &expectedSha256);
    AcquireResult commitFile(const std::string &tmpPath,
                             const std::string &expectedSha256);

    std::string root_;
};

}  // namespace advantage

#endif  // ADVANTAGE_ACQUIRE_H