From 9b1bcb111e10eac18e18c01119dac72f5133147c Mon Sep 17 00:00:00 2001 From: Julien Maffre <42961061+jumaffre@users.noreply.github.com> Date: Fri, 7 Jan 2022 15:50:34 +0000 Subject: [PATCH] Doc: reference endpoints using :http: (#3362) --- doc/build_apps/example.rst | 8 ++++---- doc/build_apps/js_app_bundle.rst | 8 ++++---- doc/build_apps/logging_cpp.rst | 4 ++-- doc/governance/accept_recovery.rst | 4 ++-- doc/operations/certificates.rst | 2 +- doc/operations/recovery.rst | 4 ++-- doc/use_apps/verify_quote.rst | 6 +++--- doc/use_apps/verify_tx.rst | 8 ++++---- 8 files changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/build_apps/example.rst b/doc/build_apps/example.rst index 01b18a11f..47b19a665 100644 --- a/doc/build_apps/example.rst +++ b/doc/build_apps/example.rst @@ -9,7 +9,7 @@ The repository contains a C++ implementation of a simple example application for The Logging application implements a trivial protocol, made up of four transaction types: -- ``POST /app/log/private``, which writes a private log message at a given index. Note that the log message will be encrypted on the ledger and only readable by nodes on the network. +- :http:POST:`/log/private`, which writes a private log message at a given index. Note that the log message will be encrypted on the ledger and only readable by nodes on the network. Log a private message: @@ -20,7 +20,7 @@ The Logging application implements a trivial protocol, made up of four transacti "msg": "A sample private log message" } -- ``GET /app/log/private``, which retrieves a private log message from a given index written by a previous ``POST /app/log/private`` call. +- :http:GET:`/log/private`, which retrieves a private log message from a given index written by a previous :http:POST:`/log/private` call. Get a private message: @@ -30,7 +30,7 @@ The Logging application implements a trivial protocol, made up of four transacti "id": 42 } -- ``POST /app/log/public``, which writes a public log message at a given index. Note that the log message will be not be encrypted and thus to anyone with access to the ledger. +- :http:POST:`/log/public`, which writes a public log message at a given index. Note that the log message will be not be encrypted and thus to anyone with access to the ledger. Log a public message: @@ -41,7 +41,7 @@ The Logging application implements a trivial protocol, made up of four transacti "msg": "A sample public log message" } -- ``GET /app/log/public``, which retrieves a public public log from a given index written by a previous ``POST /app/log/public`` call. +- :http:GET:`/log/public`, which retrieves a public public log from a given index written by a previous :http:POST:`/log/public` call. Get a public message: diff --git a/doc/build_apps/js_app_bundle.rst b/doc/build_apps/js_app_bundle.rst index 173534b7f..8fb069247 100644 --- a/doc/build_apps/js_app_bundle.rst +++ b/doc/build_apps/js_app_bundle.rst @@ -74,14 +74,14 @@ Each endpoint object contains the following information: the ``js_module``. - ``"authn_policies"``: A list of :ref:`authentication policies ` to be applied before the endpoint is executed. An empty list indicates an unauthenticated endpoint which can be called by anyone. Possible entries are: - + - ``"user_cert"`` - ``"user_signature"`` - ``"member_cert"`` - ``"member_signature"`` - ``"jwt"`` - ``"no_auth"`` - + - ``"forwarding_required"``: A string indicating whether the endpoint is always forwarded, or whether it is safe to sometimes execute on followers. Possible values are: - ``"always"`` @@ -94,7 +94,7 @@ Each endpoint object contains the following information: - ``"readonly"`` - ``"historical"`` -- ``"openapi"``: An `OpenAPI Operation Object `_ +- ``"openapi"``: An `OpenAPI Operation Object `_ without `references `_. This is descriptive but not enforced - it will be inserted into the generated OpenAPI document for this service, but will not restrict the types of the endpoint's requests or responses. @@ -155,4 +155,4 @@ If CCF is updated and introduces a newer JavaScript engine version, then any pre SUCCESS | Writing proposal to ./refresh_js_app_bytecode_cache_proposal.json SUCCESS | Wrote vote to ./refresh_js_app_bytecode_cache_vote_for.json -.. note:: The operator RPC ``/node/js_metrics`` returns the size of the bytecode and whether it is used. If it is not used, then either no bytecode is stored or it needs to be re-compiled due to a CCF update. +.. note:: The operator RPC :http:GET:`/js_metrics` returns the size of the bytecode and whether it is used. If it is not used, then either no bytecode is stored or it needs to be re-compiled due to a CCF update. diff --git a/doc/build_apps/logging_cpp.rst b/doc/build_apps/logging_cpp.rst index a73e64dbe..914716a4a 100644 --- a/doc/build_apps/logging_cpp.rst +++ b/doc/build_apps/logging_cpp.rst @@ -73,9 +73,9 @@ Each function is installed as the handler for a specific HTTP resource, defined :end-before: SNIPPET_END: install_record :dedent: -This example installs at ``"log/private", HTTP_POST``, so will be invoked for HTTP requests beginning ``POST /app/log/private``. +This example installs at ``"log/private", HTTP_POST``, so will be invoked for HTTP requests beginning :http:POST:`/log/private`. -The return value from ``make_endpoint`` is an ``Endpoint&`` object which can be used to alter how the handler is executed. For example, the handler for ``/log/private`` shown above sets a `schema` declaring the types of its request and response bodies. These will be used in calls to the ``/api`` endpoint to populate the relevant parts of the OpenAPI document. There are other endpoints installed for the URI path ``/log/private`` with different verbs, to handle ``GET`` and ``DELETE`` requests. Any other verbs, without an installed endpoint, will not be accepted - the framework will return a ``405 Method Not Allowed`` response. +The return value from ``make_endpoint`` is an ``Endpoint&`` object which can be used to alter how the handler is executed. For example, the handler for :http:POST:`/log/private` shown above sets a `schema` declaring the types of its request and response bodies. These will be used in calls to the ``/api`` endpoint to populate the relevant parts of the OpenAPI document. There are other endpoints installed for the URI path ``/log/private`` with different verbs, to handle ``GET`` and ``DELETE`` requests. Any other verbs, without an installed endpoint, will not be accepted - the framework will return a ``405 Method Not Allowed`` response. To process the raw body directly, a handler should use the general lambda signature which takes a single ``EndpointContext&`` parameter. Examples of this are also included in the logging sample app. For instance the ``log_record_text`` handler takes a raw string as the request body: diff --git a/doc/governance/accept_recovery.rst b/doc/governance/accept_recovery.rst index e81a78e77..8ae6af11e 100644 --- a/doc/governance/accept_recovery.rst +++ b/doc/governance/accept_recovery.rst @@ -55,7 +55,7 @@ To restore private transactions and complete the recovery procedure, recovery me .. note:: The recovery members who submit their recovery shares do not necessarily have to be the members who previously accepted the recovery. -Member recovery shares are stored in the ledger, encrypted with each member's public encryption key. Members can retrieve their encrypted recovery shares from the public-only service via the ``GET /gov/recovery_share`` endpoint, perform the share decryption securely (see for example :doc:`hsm_keys`) and submit the decrypted recovery share via the ``POST /gov/recovery_share`` endpoint. +Member recovery shares are stored in the ledger, encrypted with each member's public encryption key. Members can retrieve their encrypted recovery shares from the public-only service via the :http:GET:`/recovery_share` endpoint, perform the share decryption securely (see for example :doc:`hsm_keys`) and submit the decrypted recovery share via the :http:POST:`/recovery_share` endpoint. The recovery share retrieval, decryption and submission steps can be conveniently performed in one step using the ``submit_recovery_share.sh`` script: @@ -75,7 +75,7 @@ The recovery share retrieval, decryption and submission steps can be convenientl x-ms-ccf-transaction-id: 4.30 2/2 recovery shares successfully submitted. End of recovery procedure initiated. -When the recovery threshold is reached, the ``POST /gov/recovery_share`` endpoint signals that the end of the recovery procedure is initiated and the that private ledger is now being recovered. Operators and members can monitor the progress of the private recovery process via the ``GET /node/state`` endpoint. +When the recovery threshold is reached, the :http:POST:`/recovery_share` endpoint signals that the end of the recovery procedure is initiated and the that private ledger is now being recovered. Operators and members can monitor the progress of the private recovery process via the :http:GET:`/state` endpoint. .. note:: While all nodes are recovering the private ledger, no new transaction can be executed by the network. diff --git a/doc/operations/certificates.rst b/doc/operations/certificates.rst index 7cb5eb6ac..f131225dd 100644 --- a/doc/operations/certificates.rst +++ b/doc/operations/certificates.rst @@ -43,4 +43,4 @@ The procedure that operators and members should follow is summarised in the foll section Node 3 Initial Validity Period (24h default) : done, 01-03/00:00, 1d - New Joiner Validity Period : 01-03/15:00, 4d \ No newline at end of file + New Joiner Validity Period : 01-03/15:00, 4d diff --git a/doc/operations/recovery.rst b/doc/operations/recovery.rst index 5bb7bf569..876a65936 100644 --- a/doc/operations/recovery.rst +++ b/doc/operations/recovery.rst @@ -22,7 +22,7 @@ To initiate the first phase of the recovery procedure, one or several nodes shou $ cchost --config /path/to/config/file -Each node will then immediately restore the public entries of its ledger ("ledger.directory`` and ``ledger.read_only_ledger_dir`` configuration entries). Because deserialising the public entries present in the ledger may take some time, operators can query the progress of the public recovery by calling ``GET /node/state`` which returns the version of the last signed recovered ledger entry. Once the public ledger is fully recovered, the recovered node automatically becomes part of the public network, allowing other nodes to join the network. +Each node will then immediately restore the public entries of its ledger ("ledger.directory`` and ``ledger.read_only_ledger_dir`` configuration entries). Because deserialising the public entries present in the ledger may take some time, operators can query the progress of the public recovery by calling :http:GET:`/state` which returns the version of the last signed recovered ledger entry. Once the public ledger is fully recovered, the recovered node automatically becomes part of the public network, allowing other nodes to join the network. The recovery procedure can be accelerated by specifying a valid snapshot file created by the previous service in the directory specified via the ``snapshots.directory`` configuration entry. If specified, the ``recover`` node will automatically recover the snapshot and the ledger entries following that snapshot, which in practice should be a fraction of the total time required to recover the entire historical ledger.` @@ -37,7 +37,7 @@ The state machine for the ``recover`` node is as follows: PartOfPublicNetwork-- member shares reassembly -->ReadingPrivateLedger; ReadingPrivateLedger-->PartOfNetwork; -.. note:: It is possible that the length of the ledgers of each node may differ slightly since some transactions may not have yet been fully replicated. It is preferable to use the ledger of the primary node before the service crashed. If the latest primary node of the defunct service is not known, it is recommended to `concurrently` start as many nodes as previous existed in ``recover`` mode, each recovering one ledger of each defunct node. Once all nodes have completed the public recovery procedure, operators can query the highest recovered signed seqno (as per the response to the ``GET /node/state`` endpoint) and select this ledger to recover the service. Other nodes should be shutdown and new nodes restarted with the ``join`` option. +.. note:: It is possible that the length of the ledgers of each node may differ slightly since some transactions may not have yet been fully replicated. It is preferable to use the ledger of the primary node before the service crashed. If the latest primary node of the defunct service is not known, it is recommended to `concurrently` start as many nodes as previous existed in ``recover`` mode, each recovering one ledger of each defunct node. Once all nodes have completed the public recovery procedure, operators can query the highest recovered signed seqno (as per the response to the :http:GET:`/state` endpoint) and select this ledger to recover the service. Other nodes should be shutdown and new nodes restarted with the ``join`` option. Similarly to the normal join protocol (see :ref:`operations/start_network:Adding a New Node to the Network`), other nodes are then able to join the network. diff --git a/doc/use_apps/verify_quote.rst b/doc/use_apps/verify_quote.rst index 3d503d20e..76726411a 100644 --- a/doc/use_apps/verify_quote.rst +++ b/doc/use_apps/verify_quote.rst @@ -13,7 +13,7 @@ A client can verify the validity of the SGX quote of the CCF node that it connec The script verifies the target CCF node's SGX quote by: -1. Retrieving the node's SGX quote via the ``/node/quote`` endpoint. +1. Retrieving the node's SGX quote via the :http:GET:`/quotes/self` endpoint. 2. Verifying that the cryptographic hash of the node's identity public key (as presented in the node's certificate in the TLS session) matches the quote's report data. 3. Verifying that the quote's measurement (``MRENCLAVE``) matches one of the trusted enclave measurements. @@ -26,11 +26,11 @@ A specific trusted SGX enclave measurement can be specified ``--mrenclave `_. -Alternatively, the SGX quotes of all currently trusted nodes can be retrieved via the ``/node/quotes`` endpoint: +Alternatively, the SGX quotes of all currently trusted nodes can be retrieved via the :http:GET:`/quotes` endpoint: .. code-block:: bash diff --git a/doc/use_apps/verify_tx.rst b/doc/use_apps/verify_tx.rst index 19b885668..8d4f19829 100644 --- a/doc/use_apps/verify_tx.rst +++ b/doc/use_apps/verify_tx.rst @@ -8,7 +8,7 @@ Checking for Commit Because of the decentralised nature of CCF, a request is committed to the ledger only once a number of nodes have agreed on that request. -To guarantee that their request is successfully committed to the ledger, a user should issue a ``GET /tx`` request, specifying the version received in the response. This version is constructed from a view and a sequence number. +To guarantee that their request is successfully committed to the ledger, a user should issue a :http:GET:`/tx` request, specifying the version received in the response. This version is constructed from a view and a sequence number. .. code-block:: bash @@ -22,7 +22,7 @@ To guarantee that their request is successfully committed to the ledger, a user This example queries the status of transaction ID ``2.18`` (constructed from view ``2`` and sequence number ``18``). The response indicates this was successfully committed. The headers also show that the service has since made progress with other requests and changed view (``x-ms-ccf-transaction-id: 5.42``). -The possible statuses returned by ``GET /tx`` are: +The possible statuses returned by :http:GET:`/tx` are: - ``UNKNOWN`` - this node has not received a transaction with the given ID - ``PENDING`` - this node has received a transaction with the given ID, but does not yet know if the transaction has been committed @@ -56,7 +56,7 @@ This means that the request may return ``202 Accepted`` at first, with a suggest .. code-block:: bash $ curl -X GET "https:///app/receipt?transaction_id=2.23" --cacert networkcert.pem --key user0_privk.pem --cert user0_cert.pem - + {'leaf': 'fdc977c49d3a8bdf986176984e9432a09b5f6fe0c04e0b1c2dd177c03fdca9ec', 'node_id': '682c161e1bc0aec694cac58a6ea456e1caa6c9c56d8dd873da9455c341947065', 'proof': [{'left': 'f847e5efe3965b0dacb5c15c666602807a11fdecd465d0976779eed27121ffa3'}, @@ -73,7 +73,7 @@ Note that receipts over signature transactions are a special case, for example: .. code-block:: bash $ curl -X GET "https:///app/receipt?transaction_id=2.35" --cacert networkcert.pem --key user0_privk.pem --cert user0_cert.pem - + {'leaf': 'fdc977c49d3a8bdf986176984e9432a09b5f6fe0c04e0b1c2dd177c03fdca9ec', 'node_id': '06fef62c80b6471c7005c1b114166fd1b0e077845f5ad544ad4eea4fb1d31f78', 'proof': [],