Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doxy
Browse files Browse the repository at this point in the history
John-LittleBearLabs committed Nov 8, 2024
1 parent 81c5abf commit 9e50412
Showing 33 changed files with 111 additions and 18 deletions.
5 changes: 4 additions & 1 deletion library/include/ipfs_client/crypto/hasher.h
Original file line number Diff line number Diff line change
@@ -13,7 +13,10 @@ class Hasher {
public:
virtual ~Hasher() noexcept {}

virtual std::optional<std::vector<Byte>> hash(ByteView) = 0;
/*! @param bytes Bytes to hash
* @return The digest or nullopt if there was an error
*/
virtual std::optional<std::vector<Byte>> hash(ByteView bytes) = 0;
};
} // namespace ipfs::crypto

2 changes: 2 additions & 0 deletions library/include/ipfs_client/crypto/signature_verifier.h
Original file line number Diff line number Diff line change
@@ -11,6 +11,8 @@ namespace ipfs::crypto {
class SignatureVerifier {
public:
virtual ~SignatureVerifier() noexcept {}
/*! Non-owned bytes
*/
using ByteView = ipfs::ByteView;
virtual bool VerifySignature(ByteView signature,
ByteView data,
5 changes: 4 additions & 1 deletion library/include/ipfs_client/ctx/cbor_parser.h
Original file line number Diff line number Diff line change
@@ -14,7 +14,10 @@ namespace ipfs::ctx {
*/
class CborParser {
public:
virtual std::unique_ptr<DagCborValue> Parse(ByteView) = 0;
/*! @param cbor The CBOR to parse
* @return The DOM value, or NULL if there was an error
*/
virtual std::unique_ptr<DagCborValue> Parse(ByteView cbor) = 0;
virtual ~CborParser() noexcept {}
};
} // namespace ipfs::ctx
2 changes: 2 additions & 0 deletions library/include/ipfs_client/ctx/dns_txt_lookup.h
Original file line number Diff line number Diff line change
@@ -10,6 +10,8 @@ namespace ipfs::ctx {
*/
class DnsTxtLookup {
public:
/*! Callback for if usable result was achieved
*/
using DnsTextResultsCallback =
std::function<void(std::vector<std::string> const&)>;
using DnsTextCompleteCallback = std::function<void(void)>;
4 changes: 4 additions & 0 deletions library/include/ipfs_client/ctx/gateway_config.h
Original file line number Diff line number Diff line change
@@ -13,6 +13,10 @@ namespace ipfs::ctx {
class GatewayConfig {
public:
virtual ~GatewayConfig() noexcept {}
/*! Position-based access (indexing)
* @param index The 0-based index of the gateway in question
* @return The spec for the gateway iff index < count of gateways, nullopt otherwise
*/
virtual std::optional<GatewaySpec> GetGateway(std::size_t index) const = 0;
virtual unsigned GetGatewayRate(std::string_view url_prefix) = 0;
virtual int GetTypeAffinity(std::string_view url_prefix,
2 changes: 2 additions & 0 deletions library/include/ipfs_client/ctx/http_api.h
Original file line number Diff line number Diff line change
@@ -10,6 +10,8 @@ namespace ipfs::ctx {
*/
class HttpApi {
public:
/*! Description of the request to be sent
*/
using ReqDesc = ::ipfs::HttpRequestDescription;
using Hdrs = std::function<std::string(std::string_view)>;
using OnComplete = std::function<void(std::int16_t, std::string_view, Hdrs)>;
5 changes: 4 additions & 1 deletion library/include/ipfs_client/ctx/json_parser.h
Original file line number Diff line number Diff line change
@@ -14,7 +14,10 @@ namespace ipfs::ctx {
class JsonParser {
public:
virtual ~JsonParser() noexcept {}
virtual std::unique_ptr<DagJsonValue> Parse(std::string_view) = 0;
/*! @param json The JSON text to parse
* @return The DOM object or NULL if parsing failed.
*/
virtual std::unique_ptr<DagJsonValue> Parse(std::string_view json) = 0;
};
} // namespace ipfs::ctx

2 changes: 2 additions & 0 deletions library/include/ipfs_client/ctx/null_cbor_parser.h
Original file line number Diff line number Diff line change
@@ -7,6 +7,8 @@ namespace ipfs::ctx {
*/
class NullCborParser : public CborParser {
public:
/*! @return NULL, always
*/
std::unique_ptr<DagCborValue> Parse(ByteView) override {
return {};
}
4 changes: 3 additions & 1 deletion library/include/ipfs_client/gw/dnslink_requestor.h
Original file line number Diff line number Diff line change
@@ -12,7 +12,9 @@ namespace ipfs::gw {
*/
class DnsLinkRequestor final : public Requestor {
public:
explicit DnsLinkRequestor(std::shared_ptr<Client>);
/*! @param api The Client context API
*/
explicit DnsLinkRequestor(std::shared_ptr<Client> api);

HandleOutcome handle(RequestPtr) override;
std::string_view name() const override;
5 changes: 5 additions & 0 deletions library/include/ipfs_client/gw/gateway_request.h
Original file line number Diff line number Diff line change
@@ -38,6 +38,8 @@ constexpr std::size_t CAR_RESPONSE_BUFFER_SIZE = 5UL * 1024UL * 1024UL;
*/
class GatewayRequest : public std::enable_shared_from_this<GatewayRequest> {
public:
/*! Type for callbacks for when bytes are received
*/
using BytesReceivedHook =
std::function<void(std::string_view, ByteView, ipld::BlockSource const&)>;

@@ -79,6 +81,9 @@ class GatewayRequest : public std::enable_shared_from_this<GatewayRequest> {
std::string debug_string() const;
void orchestrator(std::shared_ptr<Partition> const&);
bool cachable() const;

/*! @return The part of the path that functions as an origin (the second component)
*/
std::string_view root_component() const;
void root_component(std::string_view);

6 changes: 5 additions & 1 deletion library/include/ipfs_client/gw/inline_request_handler.h
Original file line number Diff line number Diff line change
@@ -10,7 +10,11 @@ namespace ipfs::gw {
*/
class InlineRequestHandler final : public Requestor {
public:
HandleOutcome handle(RequestPtr) override;
/*! @param request The request to try handling
* @return DONE (after responding) if it was an inline request
* NOT_HANDLED otherwise
*/
HandleOutcome handle(RequestPtr request) override;
std::string_view name() const override;
};
} // namespace ipfs::gw
3 changes: 3 additions & 0 deletions library/include/ipfs_client/gw/requestor.h
Original file line number Diff line number Diff line change
@@ -41,6 +41,9 @@ class Requestor : public std::enable_shared_from_this<Requestor> {

public:
using RequestPtr = ::ipfs::gw::RequestPtr;
/*! @return The requestor's name, for debugging.
* Typically this is 1:1 with the concrete type.
*/
virtual std::string_view name() const = 0;

virtual ~Requestor() noexcept {}
3 changes: 1 addition & 2 deletions library/include/ipfs_client/gw/terminating_requestor.h
Original file line number Diff line number Diff line change
@@ -9,9 +9,8 @@ namespace ipfs::gw {
*/
class TerminatingRequestor : public Requestor {
public:
using HandleOutcome = Requestor::HandleOutcome;
std::string_view name() const override;
HandleOutcome handle(RequestPtr) override;
Requestor::HandleOutcome handle(RequestPtr) override;
};
} // namespace ipfs::gw

2 changes: 2 additions & 0 deletions library/include/ipfs_client/ipld/block_source.h
Original file line number Diff line number Diff line change
@@ -10,6 +10,8 @@ namespace ipfs::ipld {
/*! Description of where a particular block was fetched from, for diagnostics
*/
struct BlockSource {
/*! Source of now(). Defines timestamp type.
*/
using Clock = std::chrono::system_clock;

/*! Categorization of sources
3 changes: 3 additions & 0 deletions library/include/ipfs_client/ipld/dag_headers.h
Original file line number Diff line number Diff line change
@@ -14,6 +14,9 @@ class DagHeaders {
public:
void Add(BlockSource const&);
void Finish();

/*! A list of HTTP header names and values
*/
using HeaderList = std::vector<std::pair<std::string, std::string>>;

HeaderList const& headers() const { return headers_; }
8 changes: 7 additions & 1 deletion library/include/ipfs_client/ipld/dag_node.h
Original file line number Diff line number Diff line change
@@ -73,6 +73,9 @@ class DagNode : public std::enable_shared_from_this<DagNode> {
virtual ResolveResult resolve(ResolutionState& params) = 0;

protected:
/*! The child nodes of this node, possibly not yet fetched.
* @note In some cases the string is empty. For example as stem node of a UnixFS (multi-node) file.
*/
std::vector<std::pair<std::string, Link>> links_;
std::shared_ptr<Client> api_;

@@ -147,7 +150,10 @@ class DagNode : public std::enable_shared_from_this<DagNode> {
*/
virtual bool PreferOver(DagNode const& another) const;

void set_api(std::shared_ptr<Client>);
/*! Provide the Client API to be used in DAG operations
* @param api Shared pointer to API for the context being run in
*/
void set_api(std::shared_ptr<Client> api);
void source(BlockSource src) { source_ = src; }
};
} // namespace ipfs::ipld
2 changes: 1 addition & 1 deletion library/include/ipfs_client/ipld/link.h
Original file line number Diff line number Diff line change
@@ -19,7 +19,7 @@ class Link {
Ptr node;

/*! Construct an unresolved IPLD link
* @param The child's CID
* @param cid The child's CID
*/
explicit Link(std::string cid);
/*! Construct a resolved IPLD link
9 changes: 8 additions & 1 deletion library/include/ipfs_client/ipld/resolution_state.h
Original file line number Diff line number Diff line change
@@ -25,7 +25,14 @@ class ResolutionState {
BlockLookup get_available_block;

public:
ResolutionState(SlashDelimited path_to_resolve, ResponseSemantic, BlockLookup);
/*! Construct from starting info
* @param path_to_resolve Relative to the node resolve is being called on
* @param semantic If the resolution results in a stem, i.e. a directory-like not a file,
* would the preference be for a listing preview HTML page -OR-
* JSON that describes the links to files and CIDs to merge in with this JSON (in the case of a sharded dir)
* @param lookup Functor that returns a pointer to a node for a given CID if it's already availabe, nullptr otherwise.
*/
ResolutionState(SlashDelimited path_to_resolve, ResponseSemantic semantic, BlockLookup lookup);

SlashDelimited MyPath() const;
SlashDelimited PathToResolve() const;
4 changes: 3 additions & 1 deletion library/include/ipfs_client/ipns_record.h
Original file line number Diff line number Diff line change
@@ -54,7 +54,9 @@ struct ValidatedIpns {
std::string gateway_source; ///< Who gave us this record?

ValidatedIpns(); ///< Create an invalid default object
explicit ValidatedIpns(IpnsCborEntry const&);
/*! @param entry IPNS entry known to be valid
*/
explicit ValidatedIpns(IpnsCborEntry const& entry);
ValidatedIpns(ValidatedIpns&&);
ValidatedIpns(ValidatedIpns const&);
ValidatedIpns& operator=(ValidatedIpns const&);
2 changes: 1 addition & 1 deletion library/include/ipfs_client/multi_base.h
Original file line number Diff line number Diff line change
@@ -42,7 +42,7 @@ struct Codec {
* Should match the name found in the multibase table.
*/
std::string_view const name;
/*! @param Struct with the above fields filled
/*! @return Struct with the above fields filled
* @param code The multibase to fetch
*/
static Codec const* Get(Code code);
2 changes: 0 additions & 2 deletions library/include/ipfs_client/partition.h
Original file line number Diff line number Diff line change
@@ -17,8 +17,6 @@ class Client;
*/
class Partition : public std::enable_shared_from_this<Partition> {
public:
using GatewayAccess =
std::function<void(std::shared_ptr<gw::GatewayRequest>)>;
using MimeDetection = std::function<
std::string(std::string, std::string_view, std::string const&)>;
void build_response(std::shared_ptr<IpfsRequest>);
4 changes: 4 additions & 0 deletions library/include/ipfs_client/pb_dag.h
Original file line number Diff line number Diff line change
@@ -38,6 +38,10 @@ class PbDag {
* It's just a container of arbitrary bytes.
*/
PbDag(Cid const& cid, ByteView bytes);
/*! Convenience constructor
* @param cid - The CID of the block
* @param bytes - The block
*/
PbDag(Cid const& cid, std::string_view bytes);

PbDag(PbDag const&);
3 changes: 3 additions & 0 deletions library/include/ipfs_client/response.h
Original file line number Diff line number Diff line change
@@ -24,6 +24,9 @@ struct Response {
static Response PLAIN_NOT_FOUND;
static Response IMMUTABLY_GONE;
static Response HOST_NOT_FOUND_RESPONSE;
/*! @param body HTML text (the response of the body, not the `<body>`
* @param location The Location header
*/
static Response html(std::string_view body, std::string_view location = {});
};

2 changes: 2 additions & 0 deletions library/include/vocab/raw_ptr.h
Original file line number Diff line number Diff line change
@@ -37,6 +37,8 @@ class raw_ptr {
// construct. Set it to nullptr. We have time needed to read_start a word.
raw_ptr() = delete;

/*! @param p Primitive raw pointer
*/
raw_ptr(T* p) : ptr_{p} {}
raw_ptr(raw_ptr&&) = default;
raw_ptr(raw_ptr const&) = default;
2 changes: 2 additions & 0 deletions library/include/vocab/slash_delimited.h
Original file line number Diff line number Diff line change
@@ -17,6 +17,8 @@ struct SlashDelimited {

public:
SlashDelimited() : remainder_{""} {}
/*! @param unowned Text to parse into /-delimited components
*/
explicit SlashDelimited(std::string_view unowned);
explicit operator bool() const;
std::string_view pop();
6 changes: 5 additions & 1 deletion library/src/ipfs_client/gw/gateway_state.h
Original file line number Diff line number Diff line change
@@ -38,7 +38,11 @@ class GatewayState {
ctx::GatewayConfig const& cfg() const;

public:
GatewayState(std::string_view prefix, std::shared_ptr<Client>);
/*! @param prefix The URL prefix that goes in front of HTTP requests to the gateway
* e.g. https://ipfs.io/
* @param api Access to the functionality of this client's context
*/
GatewayState(std::string_view prefix, std::shared_ptr<Client> api);
long score(GatewayRequest const&, unsigned) const;
bool bored() const;
bool over_rate();
2 changes: 2 additions & 0 deletions library/src/ipfs_client/gw/multi_gateway_requestor.h
Original file line number Diff line number Diff line change
@@ -31,6 +31,8 @@ class MultiGatewayRequestor : public Requestor {
void Next();

public:
/*! @return "multi-gateway requestor"
*/
std::string_view name() const override;
HandleOutcome handle(RequestPtr) override;
};
5 changes: 4 additions & 1 deletion library/src/ipfs_client/ipld/chunk.h
Original file line number Diff line number Diff line change
@@ -16,7 +16,10 @@ class Chunk : public DagNode {
ResolveResult resolve(ResolutionState&) override;

public:
explicit Chunk(std::string);
/*! Construct
* @param bytes The blob itself
*/
explicit Chunk(std::string bytes);
~Chunk() noexcept override;
};
} // namespace ipfs::ipld
2 changes: 2 additions & 0 deletions library/src/ipfs_client/ipld/dag_cbor_node.h
Original file line number Diff line number Diff line change
@@ -12,6 +12,8 @@ class DagCborNode final : public DagNode {
ResolveResult resolve(ResolutionState&) override;

public:
/*! The dict or document being represented
*/
using Data = DagCborValue;
explicit DagCborNode(std::unique_ptr<Data>);
~DagCborNode() noexcept override;
3 changes: 3 additions & 0 deletions library/src/ipfs_client/ipld/directory_shard.h
Original file line number Diff line number Diff line change
@@ -4,6 +4,8 @@
#include <ipfs_client/ipld/dag_node.h>

namespace ipfs::ipld {
/*! A node in a sharded (HAMT) directory
*/
class DirShard : public DagNode {
std::uint64_t const fanout_;

@@ -21,6 +23,7 @@ class DirShard : public DagNode {

public:
/*! Construct with a known fanout
* @param fanout The number of buckets
*/
explicit DirShard(std::uint64_t fanout = 256UL);
~DirShard() noexcept override;
8 changes: 7 additions & 1 deletion library/src/ipfs_client/ipld/root.h
Original file line number Diff line number Diff line change
@@ -7,6 +7,9 @@
#include <optional>

namespace ipfs::ipld {
/*! Since some operations will behave differently if a given node is being treated as
* a DAG root, this proxy wraps around a node to give it those properties
*/
class Root : public DagNode {
std::optional<redirects::File> redirects_;

@@ -16,7 +19,10 @@ class Root : public DagNode {
bool expired() const override;

public:
explicit Root(std::shared_ptr<DagNode>);
/*! Construct
* @param node The actual node being treated as a DAG root
*/
explicit Root(std::shared_ptr<DagNode> node);
~Root() noexcept override;
};
} // namespace ipfs::ipld
6 changes: 6 additions & 0 deletions library/src/ipfs_client/ipld/symlink.h
Original file line number Diff line number Diff line change
@@ -12,6 +12,12 @@ class Symlink : public DagNode {
bool is_absolute() const;

public:
/*! Construct from the text of the target
* @target Either a path relative to this node's,
* OR /an/absolute/path which is relative to the DAG root
* @note If it points outside the DAG it'll be considered broken.
* This can be achieved by simply using too many ../../..
*/
explicit Symlink(std::string target);
~Symlink() noexcept override;
};
6 changes: 5 additions & 1 deletion library/src/ipfs_client/redirects.h
Original file line number Diff line number Diff line change
@@ -17,7 +17,11 @@ class Directive {
int const status_;

public:
Directive(std::string_view, std::string_view, int);
/*! @param from path/glob to match against
* @param to partial path to replace from with
* @param status HTTP status to use in successful response that hit this rule
*/
Directive(std::string_view from, std::string_view to, int status);
std::uint16_t rewrite(std::string&) const;
std::string error() const;
bool valid() const { return error().empty(); }

0 comments on commit 9e50412

Please sign in to comment.