From 7d04fac4fdda970a574159f0200e1827c0698430 Mon Sep 17 00:00:00 2001
From: Valentin Lorentz <vlorentz@softwareheritage.org>
Date: Wed, 12 Mar 2025 10:12:44 +0100
Subject: [PATCH 1/3] Document how to run the gRPC server
---
docs/grpc-api.rst | 91 +++++++++++++++++++++++++++++++++++++++++++++++
docs/index.rst | 2 ++
2 files changed, 93 insertions(+)
create mode 100644 docs/grpc-api.rst
diff --git a/docs/grpc-api.rst b/docs/grpc-api.rst
new file mode 100644
index 0000000..5b60414
--- /dev/null
+++ b/docs/grpc-api.rst
@@ -0,0 +1,91 @@
+.. _swh-provenance-grpc-api:
+
+==================
+Using the gRPC API
+==================
+
+.. highlight:: console
+
+The gRPC API is the core API used to query the provenance database remotely. It uses the
+`gRPC framework <https://grpc.io/>`_ to provide high-performance provenance answers
+with server streaming.
+
+Quickstart
+==========
+
+Building the server
+-------------------
+
+Get Rust >= 1.79, eg. with `rustup <https://rustup.rs/>`_.
+
+Run::
+
+ RUSTFLAGS="-C target-cpu=native" cargo install --locked https://gitlab.softwareheritage.org/swh/devel/swh-provenance.git
+
+Or::
+
+ git clone https://gitlab.softwareheritage.org/swh/devel/swh-provenance.git
+ cd swh-provenance
+ cargo build --release
+
+Getting a compressed provenance database
+----------------------------------------
+
+::
+
+ pip3 install awscli
+ aws s3 cp --no-sign-request --recursive s3://softwareheritage/derived_datasets/2024-12-06/provenance/all/ provenance-2024-12-06/
+
+You also need a local graph. Either use ``swh graph download`` to download a full graph, or get
+only the minimal set of required files with::
+
+ aws s3 cp --no-sign-request s3://softwareheritage/graph/2024-12-06/compressed/graph.pthash graph-2024-12-06/
+ aws s3 cp --no-sign-request s3://softwareheritage/graph/2024-12-06/compressed/graph.pthash.order graph-2024-12-06/
+ aws s3 cp --no-sign-request s3://softwareheritage/graph/2024-12-06/compressed/graph.node2swhid.bin graph-2024-12-06/
+ aws s3 cp --no-sign-request s3://softwareheritage/graph/2024-12-06/compressed/graph.node2type.bin graph-2024-12-06/
+
+
+Starting the server
+-------------------
+
+Before the first start, you need to build database indexes::
+
+ $ swh-provenance-index --database file:///provenance-2024-12-06/ --indexes provenance-2024-12-06-indexes/
+
+Or, if you installed from Git::
+
+ $ cargo run --release --bin swh-provenance-index -- --database file:///provenance-2024-12-06/ --indexes provenance-2024-12-06-indexes/
+
+The gRPC server is automatically started on port 50091 when the HTTP server
+is started with::
+
+ $ swh-provenance-grpc-serve --graph graph-2024-12-06/ --database file:///provenance-2024-12-06/ --indexes provenance-2024-12-06-indexes/
+
+Or, if you installed from Git::
+
+ $ cargo run --release --bin swh-graph-grpc-serve -- --graph graph-2024-12-06/ --database file:///provenance-2024-12-06/ --indexes provenance-2024-12-06-indexes/
+
+
+
+Running queries
+---------------
+
+The `gRPC command line tool
+<https://github.com/grpc/grpc/blob/master/doc/command_line_tool.md>`_
+can be an easy way to query the gRPC API from the command line. It is
+invoked with the ``grpc_cli`` command. Of course, it is also possible to use
+a generated RPC client in any programming language supported by gRPC.
+
+All RPC methods are defined in the service ``swh.provenance.ProvenanceService``.
+The available endpoints can be listed with ``ls``::
+
+ $ rpc_cli ls localhost:50141 swh.provenance.ProvenanceService
+ WhereIsOne
+ WhereAreOne
+
+A RPC method can be called with the ``call`` subcommand.::
+
+ $ grpc_cli call localhost:50141 swh.provenance.ProvenanceService.WhereIsOne "swhid: 'swh:1:cnt:27766b99cdcab4e9b68501c3b50f1712e016c945'"
+ swhid: "swh:1:cnt:27766b99cdcab4e9b68501c3b50f1712e016c945"
+ anchor: "swh:1:rev:1564a9e70426251655286156957f8d710f0db278"
+
diff --git a/docs/index.rst b/docs/index.rst
index f0c2c93..e196fef 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,6 +6,8 @@
:maxdepth: 2
:caption: Contents:
+ grpc-api
+
.. only:: standalone_package_doc
Indices and tables
--
GitLab
From b7290f6c9f07185039741d68b9249ea7cb28e5a1 Mon Sep 17 00:00:00 2001
From: Valentin Lorentz <vlorentz@softwareheritage.org>
Date: Wed, 12 Mar 2025 10:26:06 +0100
Subject: [PATCH 2/3] Fix copy-paste
---
docs/grpc-api.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/grpc-api.rst b/docs/grpc-api.rst
index 5b60414..06d81b3 100644
--- a/docs/grpc-api.rst
+++ b/docs/grpc-api.rst
@@ -28,8 +28,8 @@ Or::
cd swh-provenance
cargo build --release
-Getting a compressed provenance database
-----------------------------------------
+Getting a provenance database
+-----------------------------
::
--
GitLab
From 7d2427cc45c9e99b7cce6204442926136582a132 Mon Sep 17 00:00:00 2001
From: Valentin Lorentz <vlorentz@softwareheritage.org>
Date: Wed, 12 Mar 2025 10:26:54 +0100
Subject: [PATCH 3/3] Fix indent
---
docs/index.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/index.rst b/docs/index.rst
index e196fef..356c2a5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,7 +6,7 @@
:maxdepth: 2
:caption: Contents:
- grpc-api
+ grpc-api
.. only:: standalone_package_doc
--
GitLab