From e1437f5852943de9ff546d6decf67a913eaa1f10 Mon Sep 17 00:00:00 2001 From: reinkrul Date: Wed, 27 Mar 2024 09:34:26 +0100 Subject: [PATCH 1/4] Discovery: improve documentation (#2897) * Discovery: improve documentation * PR feedback * Update docs/pages/deployment/discovery.rst Co-authored-by: Wout Slakhorst * PR feedback * pr feedback --------- Co-authored-by: Wout Slakhorst --- docs/pages/deployment/discovery.rst | 76 ++++++++++++++++++++++------- 1 file changed, 59 insertions(+), 17 deletions(-) diff --git a/docs/pages/deployment/discovery.rst b/docs/pages/deployment/discovery.rst index c845e2479c..426c72179c 100644 --- a/docs/pages/deployment/discovery.rst +++ b/docs/pages/deployment/discovery.rst @@ -3,27 +3,69 @@ Discovery ######### -.. warning:: - This feature is under development and subject to change. - Discovery allows parties to publish information about themselves as a Verifiable Presentation, so that other parties can discover them for further (data) exchange. -In this Discovery Service protocol there are clients and servers: clients register their Verifiable Presentations on a server, -which can be queried by other clients. -Where to find the server and what is allowed in the Verifiable Presentations is defined in a Discovery Service Definition. -These are JSON documents that are loaded by both client and server. +A Discovery Service is hosted on a server (also a Nuts node), by an organization that is agreed upon by the parties to be the server for that particular use case. +The parties implementing that use case then configure their Nuts nodes with the service definition that defines the server. + +The service definition is a JSON document agreed upon (and loaded) by all parties that specifies: + +- which Verifiable Credentials are required for the service, +- where the Discovery Service is hosted, and +- how often the Verifiable Presentations must be updated. + +Service definitions are loaded from the ``discovery.definitions.directory`` directory by both client and server. +It does not load subdirectories. If the directory contains JSON files that are not (valid) service definitions, the node will fail to start. + +Clients +******* + +Clients will periodically query the Discovery Service for new registrations. +Applications can then search for entries in the Discovery Service (in this case ``coffeecorner``), e.g.: + +.. code-block:: http + + GET /internal/discovery/v1/discovery/coffeecorner/?credentialSubject.name=John%20Doe + +Any string property in the Verifiable Credential(s) can be queried, including nested properties. +Arrays, numbers or booleans are not supported. Wildcards can be used to search for partial matches, e.g. ``Hospital*`` or ``*First``. +If multiple query parameters are specified, all of them must match a single Verifiable Credential. + +Registration +============ + +To register a DID on a Discovery Service, the DID must be activated for the service. +The Nuts node will then register a Verifiable Presentation of the DID on the service, and periodically refresh it. +E.g., for service ``coffeecorner`` and DID ``did:web:example.com``: + +.. code-block:: http + + POST /internal/discovery/v1/coffeecorner/did:web:example.com + +The DID's wallet must contain the Verifiable Credential(s) that are required by the service definition, +otherwise registration will fail. If the wallet does not contain the credentials, +the Nuts node will retry registration periodically. + +Servers +******* +To act as server for a specific discovery service, its service ID needs to be specified in ``discovery.server.ids``, e.g.: + +.. code-block:: yaml + + discovery: + server: + ids: + - "coffeecorner" + +The IDs in this list must correspond to the ``id`` fields of the loaded service definition, otherwise the node will fail to start. + +Clients will access the discovery service through ``/discovery`` on the external HTTP interface, so make sure it's available externally. -The Nuts node always acts as client for every loaded service definition, meaning it can register itself on the server and query it. -It only acts as server for a specific server if configured to do so. +The endpoint for a Discovery Service MUST be in the following form (unless mapped otherwise in a reverse proxy): -Configuration -************* +.. code-block:: http -Service definitions are JSON files loaded from the ``discovery.definitions`` directory. -It loads all files wih the ``.json`` extension in this directory. It does not load subdirectories. -If the directory contains JSON files that are not (valid) service definitions, the node will fail to start. + https:///discovery/ -To act as server for a specific discovery service definition, -the service ID from the definition needs to be specified in ``discovery.server.ids``. -The IDs in this list must correspond to the ``id`` fields of the loaded service definition, otherwise the node will fail to start. \ No newline at end of file +Where ```` is the ID of the service, e.g.: ``/discovery/coffeecorner``. \ No newline at end of file From 803a3a51c416e1ab32cc58c4dcbd6e021b2ba88a Mon Sep 17 00:00:00 2001 From: Gerard Snaauw <33763579+gerardsn@users.noreply.github.com> Date: Wed, 27 Mar 2024 14:12:23 +0100 Subject: [PATCH 2/4] cancel superseded docker build actions (#2981) --- .github/workflows/build-images.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/build-images.yaml b/.github/workflows/build-images.yaml index e900923a93..010ad898ab 100644 --- a/.github/workflows/build-images.yaml +++ b/.github/workflows/build-images.yaml @@ -11,6 +11,11 @@ on: branches: - master +# cancel build action if superseded by new commit on same branch +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + jobs: docker: runs-on: ubuntu-latest From ba11e72b89c24c129eceedde9b283c75a404139c Mon Sep 17 00:00:00 2001 From: reinkrul Date: Thu, 28 Mar 2024 09:10:53 +0100 Subject: [PATCH 3/4] Docs: change Discovery HTTP code blocks to normal code blocks (highlighting is weird) (#2985) --- docs/pages/deployment/discovery.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/deployment/discovery.rst b/docs/pages/deployment/discovery.rst index 426c72179c..b49bb5322e 100644 --- a/docs/pages/deployment/discovery.rst +++ b/docs/pages/deployment/discovery.rst @@ -24,7 +24,7 @@ Clients Clients will periodically query the Discovery Service for new registrations. Applications can then search for entries in the Discovery Service (in this case ``coffeecorner``), e.g.: -.. code-block:: http +.. code-block:: GET /internal/discovery/v1/discovery/coffeecorner/?credentialSubject.name=John%20Doe @@ -39,7 +39,7 @@ To register a DID on a Discovery Service, the DID must be activated for the serv The Nuts node will then register a Verifiable Presentation of the DID on the service, and periodically refresh it. E.g., for service ``coffeecorner`` and DID ``did:web:example.com``: -.. code-block:: http +.. code-block:: POST /internal/discovery/v1/coffeecorner/did:web:example.com @@ -64,7 +64,7 @@ Clients will access the discovery service through ``/discovery`` on the external The endpoint for a Discovery Service MUST be in the following form (unless mapped otherwise in a reverse proxy): -.. code-block:: http +.. code-block:: https:///discovery/ From eea88afb6bc41619fa6a279816a1f1bb752abb31 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 28 Mar 2024 14:38:41 +0100 Subject: [PATCH 4/4] Bump gorm.io/gorm from 1.25.8 to 1.25.9 (#2996) Bumps [gorm.io/gorm](https://github.com/go-gorm/gorm) from 1.25.8 to 1.25.9. - [Release notes](https://github.com/go-gorm/gorm/releases) - [Commits](https://github.com/go-gorm/gorm/compare/v1.25.8...v1.25.9) --- updated-dependencies: - dependency-name: gorm.io/gorm dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- go.mod | 2 +- go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index 86c1d024d3..0d24a454d4 100644 --- a/go.mod +++ b/go.mod @@ -166,7 +166,7 @@ require ( google.golang.org/genproto/googleapis/rpc v0.0.0-20240123012728-ef4313101c80 // indirect gopkg.in/Regis24GmbH/go-diacritics.v2 v2.0.3 // indirect gorm.io/driver/sqlite v1.5.5 - gorm.io/gorm v1.25.8 + gorm.io/gorm v1.25.9 rsc.io/qr v0.2.0 // indirect ) diff --git a/go.sum b/go.sum index 01821ebf5f..56022c374d 100644 --- a/go.sum +++ b/go.sum @@ -920,8 +920,8 @@ gorm.io/driver/sqlserver v1.5.2 h1:+o4RQ8w1ohPbADhFqDxeeZnSWjwOcBnxBckjTbcP4wk= gorm.io/driver/sqlserver v1.5.2/go.mod h1:gaKF0MO0cfTq9Q3/XhkowSw4g6nIwHPGAs4hzKCmvBo= gorm.io/gorm v1.25.2-0.20230610234218-206613868439/go.mod h1:L4uxeKpfBml98NYqVqwAdmV1a2nBtAec/cf3fpucW/k= gorm.io/gorm v1.25.7/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8= -gorm.io/gorm v1.25.8 h1:WAGEZ/aEcznN4D03laj8DKnehe1e9gYQAjW8xyPRdeo= -gorm.io/gorm v1.25.8/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8= +gorm.io/gorm v1.25.9 h1:wct0gxZIELDk8+ZqF/MVnHLkA1rvYlBWUMv2EdsK1g8= +gorm.io/gorm v1.25.9/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8= honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= rsc.io/qr v0.2.0 h1:6vBLea5/NRMVTz8V66gipeLycZMl/+UlFmk8DvqQ6WY=