From 118cb98e25952016ca7a0a3d77bd85e64277d47c Mon Sep 17 00:00:00 2001
From: Matthias Mohr <webmaster@mamo-net.de>
Date: Thu, 20 Jun 2024 17:51:25 +0200
Subject: [PATCH] Add Remote UDP extension #515

---
 CHANGELOG.md                    |  5 +++
 README.md                       |  1 +
 extensions/remote-udp/README.md | 65 +++++++++++++++++++++++++++++++++
 3 files changed, 71 insertions(+)
 create mode 100644 extensions/remote-udp/README.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7622bc24..baf9432a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased / Draft
 
+### Added
+
+- **New extensions:**
+    - [Remote UDP Extension](./extensions/remote-udp/README.md)
+
 ### Fixed
 
 - `GET /file_formats`: Base paramater on top of normal JSON Schema, not Process JSON Schema
diff --git a/README.md b/README.md
index aef37924..6e244af0 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,7 @@ See also the [changelog](CHANGELOG.md) and the [milestones](https://github.com/O
 | ---------------------------------------------- | ------- | ------------ | ----------- |
 | [Commercial Data](extensions/commercial-data/) | 0.1.0   | experimental | Provides an interface for discovering, ordering and using commercial data. |
 | [Federation](extensions/federation/)           | 0.1.0   | experimental | Covers federation aspects, i.e. where multiple back-ends are exposed as a single API. |
+| [Remote UDP](extensions/remote-udp/)           | 0.1.0   | experimental | Load user-defined processes that are hosted on other hosts through the process namespace into process graphs. |
 
 ## Repository
 
diff --git a/extensions/remote-udp/README.md b/extensions/remote-udp/README.md
new file mode 100644
index 00000000..3ffa1e1a
--- /dev/null
+++ b/extensions/remote-udp/README.md
@@ -0,0 +1,65 @@
+# Remote UDP Extension
+
+The openEO API is a specification for interoperable cloud-based processing of large Earth observation datasets.
+
+This extension enables user to load user-defined processes that are hosted on other hosts through the process namespace into process graphs.
+
+- Version: **0.1.0**
+- Stability: **experimental**
+- Conformance class: `https://api.openeo.org/extensions/remote-udp/0.1.0`
+
+## Justification
+
+The openEO API defines the `namespace` property in a process node of a process graph as follows:
+>  The following options are predefined by the openEO API, but additional namespaces may be introduced by back-ends or in a future version of the API.
+> * `null` [...]
+> * `backend` [...]
+> * `user` [...]
+
+This makes it possible that this extension adds additional allowed values to the `namespace` property.
+
+## Specification
+
+This extension extends the `namespace` property of process graph nodes so that it accepts **absolute** URL with the protocols `https` (**recommended**) and `http` (discouraged). The URLs specified MUST either return
+
+1. a single process (compatible to the endpoint `GET /process_graphs/{process_graph_id}`)
+2. a list of processes (compatible to the endpoint `GET /process_graphs`)
+
+If a URL is provided for the `namespace` property, the `id` property of the process graph node MUST be set to the `id` of the process.
+
+### Compatibility
+
+Compatible means in this context that the requests and responses must comply to the openEO API specification with the following exceptions:
+
+- The `Authorization` header is not required and will usually not be sent.
+- Lists of processes MUST NOT paginate and the full process description MUST be provided for each process (i.e., the recommendation to omit large properties such as `process_graph` doesn't apply).
+
+### Client Considerations
+
+Clients MUST only offer this functionality to users if the conformance class of this extension is listed in the `conformsTo` property of the `GET /` endpoint.
+
+The protocol `http` is discouraged for URLs as web-based clients may not be able to retrieve HTTP URLs from a HTTPS context.
+For the same reason it is also RECOMMENDED to enable CORS for all URLs.
+
+### Error Handling
+
+The following error SHOULD be reported if the namespace can't be resolved:
+
+- Code: `ProcessNamespaceInvalid`
+- Message: `The value passed for namespace '{namespace}' in process '{process}' is invalid: {reason}`
+- HTTP Status Code: 400
+
+## Example
+
+An exemplary process graph node:
+
+```json
+{
+    "process_id": "echo",
+    "namespace": "https://hub.openeo.org/processes/echo",
+    "arguments": {
+    	"message": "Hello World"
+	},
+    "result": true
+}
+```