library/readme

little-bear-labs · Feb 19, 2024 · 9f74278 · 9f74278
1 parent ae161ea
commit 9f74278
Show file tree

Hide file tree

Showing 24 changed files with 86 additions and 24 deletions.
diff --git a/chromium_edits/123.0.6272.0/components/cbor/reader.cc.patch b/chromium_edits/123.0.6272.0/components/cbor/reader.cc.patch
@@ -14,7 +14,8 @@ index 3c31e3d05e5d3..b0cf411b350e2 100644
 @@ -157,6 +157,10 @@ std::optional<Value> Reader::DecodeCompleteDataItem(const Config& config,
        // Floating point values also go here since they are also type 7.
        return DecodeToSimpleValueOrFloat(*header, config);
-     case Value::Type::TAG:  // We explicitly don't support TAG.
+-    case Value::Type::TAG:  // We explicitly don't support TAG.
++    case Value::Type::TAG:
 +      if (config.parse_tags) {
 +        return ReadTagContent(*header, config, max_nesting_level);
 +      }

diff --git a/component/chromium_ipfs_context.h b/component/chromium_ipfs_context.h
@@ -5,7 +5,7 @@
 #include "preferences.h"
 
 #include <ipfs_client/block_storage.h>
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 
 #include <base/memory/raw_ref.h>
 #include <base/time/time.h>

diff --git a/component/dns_txt_request.h b/component/dns_txt_request.h
@@ -1,7 +1,7 @@
 #ifndef IPFS_DNS_TXT_REQUEST_H_
 #define IPFS_DNS_TXT_REQUEST_H_
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 
 #include <mojo/public/cpp/bindings/receiver.h>
 #include <services/network/public/cpp/resolve_host_client_base.h>

diff --git a/library/README.md b/library/README.md
@@ -1,6 +1,66 @@
 # ipfs-client
 
-## TODO
+## Usage
 
-Need to fill out this README to explain how to use ipfs-client in other contexts.
 
+
+### Instantiate ipfs::Client
+
+Using code should center on the `ipfs::Client` class found in `include/ipfs_client/client.h`
+There are a number of customization points for that class, particularly those things which might vary depending on 
+which dependencies you'd like to use and/or which behaviors you'd like. 
+
+Some concrete classes are provided with the library, each turned off if the corresponding dependency does not appear to 
+be available. If you're using the Conan package, and not on Windows, all those libraries should be already linked in for you. 
+In that case, you may use `ipfs::start_default` found in `include/ipfs_client/opinionated_context.h` , which is suitable for some non-critical uses.
+
+If any of these choices don't make sense for your project, you may create a concrete class for whichever interface you need to alter, and call `with()` on the Client object, passing in an instance of your class.
+If you don't call `with()`, usually you get an implementation that simply doesn't do anything (null object), or does something very simplistic.
+
+To see the sorts of extension points available, look at the various `with()` methods in `ipfs::Client`. For example:
+
+| Interface                         | Function                                                             | Provided example implementation                         | Design choice in example                                                                                                |
+|-----------------------------------|----------------------------------------------------------------------|---------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
+| ipfs::ctx::HttpApi                | Make HTTP(s) requests                                                | ipfs::ctx::BoostBeastHttp                               | Uses [Boost.Beast](https://www.boost.org/doc/libs/1_84_0/libs/beast/doc/html/index.html)                                |
+| ipfs::ctx::DnsTxtLookup           | DNS TXT requests (not name resolution)                               | ipfs::ctx::AresDnsTxtLookup                             | Uses [c-ares](https://c-ares.org/)                                                                                      |
+| ipfs::ctx::GatewayConfig          | Configures which IPFS gateways you use and how                       | ipfs::ctx::TransitoryGatewayConfig                      | Loads IPFS_GATEWAY environment variable, or if not set a static list of gateways. Changes at runtime are not persisted. |
+| ipfs::ctx::JsonParser             | Parses JSON (String -> ipfs::DagJsonValue)                           | ipfs::ctx::NlohmannJsonParser                           | Uses N. Lohmann's [JSON for Modern C++](https://github.com/nlohmann/json)                                               |
+| ipfs::ctx::CborParser             | Parses CBOR (Bytes -> ipfs::DagCborValue)                            | ipfs::ctx::NlohmannCborParser                           | Uses N. Lohmann's [JSON for Modern C++](https://github.com/nlohmann/json), but for CBOR                                 |
+| ipfs::gw::Requestor               | A chain-of-responsibility for processing IPFS requests               | ipfs::gw::default_requestor() returns common requestors | If you don't provide an argument, this chain does no caching.                                                           |  
+| MimeTypeDeduction                 | A function that guesses the mime type of a doc given its head & path | ipfs::util::TrivialMimeGuess                            | Doesn't even look at file content, just uses extension. Fine for cases that don't really need the mime type.            |
+| UrlUnescaping                     | Given a URL component (i.e. in-between `/`s), deal with % escaping   | ipfs::util::RoughlyUnescapeUrlComponent                 | Not a complete implementation, but deals with some common cases.                                                        |
+| ipfs::crypto::SignatureVerifier   | Verifies a public key signature for a particular type of key         | ipfs::crypto::OpensslSignatureVerifier                  | Uses OpenSSL, but only for RSA & Ed25519 keys (others are dropped)                                                      |
+
+### Get a partition
+
+`ipfs::Client::partition()` takes an arbitrary string to use as a key for that partition. 
+The scheme for the keys is whatever you'd like it to be, but if you pass in an identical key you'll get the same partition back each time.
+If it's the first time for that key, a new object is created, including an isolated view of the DAGs.
+
+If you are not in a security-critical case, it's entirely reasonable to pass in `""` every time.
+You might also consider using URL origins to define partitioning.
+
+### Make a request
+
+`std::make_shared<IpfsRequest>(path, callback)`
+
+* path - A string of the form /ipfs/<cid>/path/to/file or /ipns/<key or hostname>/path/to/file
+* callback - What to call when a final response is formed.
+
+Pass the request to `partition->build_response()`
+
+### Drive your HttpApi and DnsTxtLookup implementations
+
+Many implementations will need some sort of event loop. Do that.
+
+### Handle response
+
+The callback you passed to create the request. 
+Be sure to check the second parameter's (the response's) status_ field, which contains HTTP statuses like:
+
+* 200 - success
+* 404 - unable to find it from known gateways (possibly timed out)
+* 410 - That path does not exist in that DAG, provably. 
+* 503 - Unable to resolve IPNS name (either DNSLink failed to resolve or gateways didn't have the IPNS record, as appropriate)
+
+Depending on quirks of your various implementations you may need to do extra logic here.
diff --git a/library/include/ipfs_client/context_api.h → library/include/ipfs_client/client.h b/library/include/ipfs_client/context_api.h → library/include/ipfs_client/client.h
@@ -56,6 +56,7 @@ class Client : public std::enable_shared_from_this<Client> {
   ctx::JsonParser& json();
   ctx::CborParser& cbor();
   std::shared_ptr<gw::Requestor> requestor();
+
   Client& with(std::unique_ptr<ctx::HttpApi>);
   Client& with(std::unique_ptr<ctx::DnsTxtLookup>);
   Client& with(std::unique_ptr<ctx::GatewayConfig>);

diff --git a/library/include/ipfs_client/gw/gateway_request.h b/library/include/ipfs_client/gw/gateway_request.h
@@ -2,7 +2,7 @@
 #define IPFS_TRUSTLESS_REQUEST_H_
 
 #include <ipfs_client/cid.h>
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 
 #include <vocab/flat_mapset.h>
 #include <vocab/slash_delimited.h>

diff --git a/library/include/ipfs_client/opinionated_context.h b/library/include/ipfs_client/opinionated_context.h
@@ -5,7 +5,7 @@
 #include <ipfs_client/ctx/ares_dns_txt_lookup.h>
 #include <ipfs_client/ctx/boost_beast_http.h>
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 #include <ipfs_client/partition.h>
 
 #include <memory>

diff --git a/library/src/ipfs_client/car.cc b/library/src/ipfs_client/car.cc
@@ -1,6 +1,6 @@
 #include "car.h"
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 
 #include <libp2p/multi/uvarint.hpp>
 

diff --git a/library/src/ipfs_client/context_api.cc → library/src/ipfs_client/client.cc b/library/src/ipfs_client/context_api.cc → library/src/ipfs_client/client.cc
@@ -1,4 +1,4 @@
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 
 #include "crypto/openssl_sha2_256.h"
 #include "ipfs_client/crypto/openssl_signature_verifier.h"

diff --git a/library/src/ipfs_client/context_api_unittest.cc b/library/src/ipfs_client/context_api_unittest.cc
@@ -1,4 +1,4 @@
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 
 #include <gtest/gtest.h>
 

diff --git a/library/src/ipfs_client/gw/dnslink_requestor.cc b/library/src/ipfs_client/gw/dnslink_requestor.cc
@@ -5,7 +5,7 @@
 #include <ipfs_client/gw/gateway_request.h>
 #include <ipfs_client/ipld/dag_node.h>
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 #include <ipfs_client/ipfs_request.h>
 #include <ipfs_client/partition.h>
 

diff --git a/library/src/ipfs_client/gw/multi_gateway_requestor.h b/library/src/ipfs_client/gw/multi_gateway_requestor.h
@@ -5,7 +5,7 @@
 
 #include <ipfs_client/gw/requestor.h>
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 
 #include <deque>
 #include <map>

diff --git a/library/src/ipfs_client/gw/providers_response.cc b/library/src/ipfs_client/gw/providers_response.cc
@@ -1,6 +1,6 @@
 #include "providers_response.h"
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 #include <ipfs_client/dag_json_value.h>
 
 #include <vocab/slash_delimited.h>

diff --git a/library/src/ipfs_client/ipld/dag_cbor_node.h b/library/src/ipfs_client/ipld/dag_cbor_node.h
@@ -3,7 +3,7 @@
 
 #include <ipfs_client/ipld/dag_node.h>
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 
 namespace ipfs::ipld {
 class DagCborNode final : public DagNode {

diff --git a/library/src/ipfs_client/ipld/dag_node.cc b/library/src/ipfs_client/ipld/dag_node.cc
@@ -10,7 +10,7 @@
 #include "symlink.h"
 #include "unixfs_file.h"
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 #include <ipfs_client/ipns_record.h>
 #include <ipfs_client/pb_dag.h>
 

diff --git a/library/src/ipfs_client/ipld/directory_shard.cc b/library/src/ipfs_client/ipld/directory_shard.cc
@@ -2,7 +2,7 @@
 
 #include "log_macros.h"
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 #include <vocab/endian.h>
 
 #include <smhasher/MurmurHash3.h>

diff --git a/library/src/ipfs_client/ipld/resolution_state.cc b/library/src/ipfs_client/ipld/resolution_state.cc
@@ -1,6 +1,6 @@
 #include <ipfs_client/ipld/resolution_state.h>
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 
 using Self = ipfs::ipld::ResolutionState;
 

diff --git a/library/src/ipfs_client/ipld/small_directory.cc b/library/src/ipfs_client/ipld/small_directory.cc
@@ -1,6 +1,6 @@
 #include "small_directory.h"
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 #include "ipfs_client/generated_directory_listing.h"
 #include "ipfs_client/path2url.h"
 

diff --git a/library/src/ipfs_client/ipns_record.cc b/library/src/ipfs_client/ipns_record.cc
@@ -1,7 +1,7 @@
 #include <ipfs_client/ipns_record.h>
 
 #include <ipfs_client/cid.h>
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 #include <ipfs_client/dag_cbor_value.h>
 
 #include "log_macros.h"

diff --git a/library/src/ipfs_client/partition.cc b/library/src/ipfs_client/partition.cc
@@ -1,6 +1,6 @@
 #include "ipfs_client/partition.h"
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 #include <ipfs_client/ipfs_request.h>
 
 #include "log_macros.h"

diff --git a/library/src/ipfs_client/pb_dag.cc b/library/src/ipfs_client/pb_dag.cc
@@ -1,6 +1,6 @@
 #include "ipfs_client/pb_dag.h"
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 
 #include "log_macros.h"
 

diff --git a/test_data/include/mock_api.h b/test_data/include/mock_api.h
@@ -3,7 +3,7 @@
 
 #include <gtest/gtest.h>
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 #include <ipfs_client/json_cbor_adapter.h>
 
 #include "mock_gw_cfg.h"

diff --git a/test_data/include/mock_cbor.h b/test_data/include/mock_cbor.h
@@ -1,7 +1,7 @@
 #ifndef IPFS_MOCK_BOR_H_
 #define IPFS_MOCK_BOR_H_
 
-#include "ipfs_client/context_api.h"
+#include "ipfs_client/client.h"
 
 #include <gtest/gtest.h>
 

diff --git a/test_data/include/mock_requestor.h b/test_data/include/mock_requestor.h
@@ -1,7 +1,7 @@
 #ifndef IPFS_TEST_REQUESTOR_H_
 #define IPFS_TEST_REQUESTOR_H_
 
-#include <ipfs_client/context_api.h>
+#include <ipfs_client/client.h>
 #include <ipfs_client/gw/requestor.h>
 
 #include <gtest/gtest.h>