Merge branch 'master' into mitzXnuts

* master:
  Bump gorm.io/gorm from 1.25.8 to 1.25.9 (#2996)
  Docs: change Discovery HTTP code blocks to normal code blocks (highlighting is weird) (#2985)
  cancel superseded docker build actions (#2981)
  Discovery: improve documentation (#2897)

.github/workflows/build-mitzXnuts-poc-images.yaml

@@ -9,6 +9,11 @@ on:
     branches:
       - mitzXnuts
 
+# 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

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::
+
+    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::
+
+    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::
 
-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://<host>/discovery/<service_id>
 
-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.
+Where ``<service_id>`` is the ID of the service, e.g.: ``/discovery/coffeecorner``.

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
 )
 

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=