[GAP-17] Offline requestor model

gaps/gap-17_offline_requestor_model/gap-17_offline_requestor_model.md

@@ -0,0 +1,145 @@
+---
+gap: GAP-17
+title: Offline Requestor Model
+description: Considerations and features required to implement Golem applications where Requestor is not required to be constantly connected to the network.
+author: stranger80 (@stranger80)
+status: Draft
+type: Feature
+---
+
+## Abstract
+Golem Network is a space where Requestors and Providers interact to trade computing resources in exchange for crypto-tokens. Such collaboration may not require constant connection between Requestor and Providers of the resources. The connectivity may also be disrupted by such events as machine failures & outages, network issues, etc. This article considers a number of scenarios where Requestor is not required to remain constantly online, and introduces a number of features required to support such scenarios in Golem ecosystem. 
+
+## Motivation
+The features indicated or referenced in this GAP are intended to meet following objectives:
+- Improve application resilience to network & requestor node failures
+- Enable "fire&forget", and self-sustaining application models
+
+## Specification
+Three "Offline Requestor" scenarios are considered in this GAP. 
+
+#### **A. Requestor partially connected**
+Characteristics:
+- Requestor daemon remains online until Agreement is signed and Activity started
+- Requestor daemon may then disconnect while the Activity is in progress
+- Requestor daemon may reconnect at any time, and exercise control over the Activity via ExeScript
+
+**Notes:**
+- This scenario is only possible with payment schemes which:
+  * either assume upfront payment, 
+  * or allow long intervals between payments,
+  * or are self-sustained and not depending on the presence of the daemon.
+
+#### **B. Requestor offline ("fire&forget")** 
+Characteristics:
+- Requestor daemon remains online until Agreement is signed and Activity started
+- Requestor daemon disconnects permanently, while the Activity continues (probably until agreed computation is complete, or funds run out)
+
+**Notes:**
+- This scenario is only possible with payment schemes which:
+  * either assume upfront payment, 
+  * or allow long intervals between payments,
+  * or are self-sustained and not depending on the presence of the daemon.
+
+#### **C. Requestor delegates control**
+Characteristics:
+- Requestor daemon remains online until Agreement is signed and Activity started
+- Requestor daemon transfers grants control rights to another node/identity, which remains online and exercises control over the Activity 
+
+**Notes:**
+- This requires **Agreement Permissions Management** feature
+
+### Proposed features
+
+This GAP introduces following features which are aimed at enabling the "offline Reuqestor" scenarios listed above:
+- Activity Attach/Detach
+- Self-sustained Payments
+- Agreement Permissions Management
+
+The mapping between the scenarios and features required to implement them is indicated below:
+
+| | Activity attach/detach | Self-sustained payments | Agreement Permissions Management |
+|-|-|-|-|
+| Requestor partially connected     | X | X | |
+| Requestor offline ("fire&forget") | X | X | |
+| Requestor delegates control       | X | | X |
+|        |  | |  |
+
+#### **Feature: Activity attach/detach**
+We propose to introduce an ability for Requestor node to disconnect from the network while controlled Activity remains active, and then gracefully reconnect, and take control of the Activity. **Note** this can happen intentionally, or as a result of eg. a network failure or software error. Therefore the ability to attach a Requestor to resume control over an Activity is improving the reliability and robustness of Golem as a platform. 
+
+The implementation of this feature requires considerations on two levels:
+
+1. Requestor Agent application goes offline, while corresponding `yagna` daemon remains online 
+    - The HL API implementations shall include the ability to obtain a "live" instance of Activity object and corresponding Agreement object based on `activityID`, and then perform actions on them (ExeScript command execution and results processing, Agreement control, including termination), as in the following pseudo-code example:
+       ```
+       ...
+       activity = Golem.attach_activity(activityId)   # returns an "attached" Activity object, which can then be used to manipulate the Activity
+
+       exeScriptResult = activity.exec(exeScript)     # Activity can receive ExeScript commands, etc.
+
+       activity.agreement.terminate(reason)           # ...eventually the corresponding Agreement can be terminated
+       ...
+       ```
+    - Persisting the information about running Activities to which an HL API caller may "attach" is out of scope for HL API implementation, ie. it is the designer of the Requestor Agent application, whois responsible for eg. persisitng the obtained `activityIDs`, in order to be able to "attach" to Activities which are "in-flight".   
+    - TBC decide how to approach the Task and Service objects.
+
+2. Requestor `yagna` daemon goes offline and should have ability to reconnect to network
+    - The daemon may disconnect from the network, and the current state of the Golem node (incuding Demands/Offers, Agreements, Acitivites, etc.) should be persisted.
+    - The daemon may re-connect to the network, and it should be capable of synchronizing the persisted state with the actual state of relevant entities on the network (eg. update the actual state of Agreements, Activities, respective Invoices/DebitNotes, events, etc.)
+    - After the reconnecting and successful synchronization, the `yagna` APIs should continue to work as if there was no offline period. 
+
+**'Detach' and in-flight operations**
+
+It shall be acceptable for 'detach' to happen while there are API calls in-flight. 
+
+For long-polling API calls (eg. `collectDemands`/`collectOffers`, `getExecBatchResults`) the 'detach' should break the running API calls. 
+- For scenario when Agent application goes offline - the daemon implementation shall persist the relevant data structures, so that after subsequent 'attach' the Agent may query for data received by the deamon while the Agent remained offline.
+- For scenario when daemon goes offline - the Golem network protocol shall ensure that relevant data objects are persisted on sender side, and delivered after the daemon subsequently 'attaches' itself.
+
+**Note:** The `getExecBatchResults` API called in `text/event-stream` ('streaming') mode will not attempt to persist the undelivered stream content while calling Agent/daemon remains offline. The same API called in `application/json` ('non-streaming') mode will operate as described above.
+
+#### **Feature: Self-sustained payments**
+A `yagna` Payment Platform abstraction is proposed which implements the standard Payment API logic (Invoice/DebitNote issuance, Payment processing), however does not require the Requestor to be online to accept Invoices/DebitNotes. 
+
+Such a self-sustained Payment Platform shall be implemented as standard payment platform, where Provider-side Payment API calls are not routed to Requestor node (and corresponding Agent application), but instead are handled by a party, which provides the "Accept/Reject" logic, and is able to lauch respective payments on behalf of the Reuqestor who signed the Agreement.
+
+The "payment issuing" party can be for example:
+- A "payment depositary/broker" service, which accepts prepayment from the Reuqestor, as well as instructions on how the funds can be released (which can be as simple as "release x GLM per block on bloackchain", or may include more sophisticated Invoice acceptance logic).
+- A "payment channel" smart-contract on a blockchain network.
+
+**In general,** the self-sustained Payment mechanism shall be expressed in Demand&Offer via dedicated, standardized properties from `golem.com.payment` property namespace. This is important, as a specific payment platform & scheme are required to ensure compatibility between Requestor and Provider nodes to support a specific "offline Requestor" scenario.
+
+#### **Feature: Agreement Permissions Management**
+In order to support scenarios where control delegation from Requestor to a different Golem node is performed, the Golem APIs must include a concept of permissions and grants. 
+
+This feature is described in a dedicated [GAP-24](). 
+
+## Rationale
+The proposed behaviour of 'attach/detach' feature is driven by intent to increase robustness of Golem platform, and expand the space of supported usage scenarios, but also taking into account the state of existing `yagna` implementation. It is assumed that the implementaion of the proposed feature logic would not imply substantial redesign of Golem network protocols & implementations.
+
+## Backwards Compatibility
+Backwards compatibility can be considered separately for each feature proposed.
+### Activity attach/detach
+
+#### 1. Requestor Agent application goes offline - `yagna` daemon remains online
+This scenario is implemented only on Agent application level (so in HL API library), so backwards compatibility is ensured between a "new" HL API library implementation and "legacy" `yagna` daemon implementation (as no `yagna` REST API changes are required).
+
+#### 2. Requestor `yagna` daemon goes offline
+**IMPORTANT** Will current Golem net implementations (eg. "hybrid net") support a scenario where `yagna` daemon is reconnecting to network after downtime?
+
+### Self-sustained payments
+As self-susteined payment mechanisms are to be provided by specific, distinguished payment platform & scheme implementations, the Golem nodes and Agent applications will ensure compatibility by indicating respective payment conditions via properties & constraints in Demands & Offers. Therefore only nodes which support self-sustained payments will enter an Agreement, so backwards compatibility will be ensured.
+
+### Agreement Permissions Management
+See relevant [GAP-24]() for details.
+
+## Test Cases
+Indicative test scenario suite is available [here](gap-17_test_cases.md). 
+
+## Security Considerations
+Considerations must be given to all vulnerabilities which may result from a fact that the original Requestor (who signed the Agreement) disconnects from the network, leaving the Provider 'unattended'. A malicious 'usurper' may be tempted to disguise as the original Requestor to gain control over the in-flight Agreements&Activites. 
+It seems mandatory to ensure the communciation security (ie. message integrity and authentication) is achieved on Golem Net level - so that the Golem Net transport layer ensures the identity of the sender of data over the network.
+
+## Copyright
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

gaps/gap-17_offline_requestor_model/gap-17_test_cases.md

@@ -0,0 +1,71 @@
+# Offline Requestor Model - Test Scenarios
+
+## 1. Requestor partially connected
+
+### 1.1. Requestor Agent outage
+1. Launch & initialize Requestor `yagna` daemon
+2. Launch Requestor Agent to start an interactive service payload on a VM 
+3. Execute a simple ExeScript batch to ensure successful interaction with payload
+4. Shutdown the Requestor Agent
+5. Restart the Requestor Agent
+6. Execute a simple ExeScript batch to ensure the Requestor Agent application has successfully reconnected to the Daemon
+
+### 1.2. Requestor Daemon outage
+1. Launch & initialize Requestor `yagna` daemon
+2. Launch Requestor Agent to start an interactive service payload on a VM 
+3. Execute a simple ExeScript batch to ensure successful interaction with payload
+4. Shutdown the Requestor Daemon
+5. Restart the Requestor Daemon
+6. Execute a simple ExeScript batch to ensure the Daemon has successfully reconnected
+
+### 1.3. Network disruption
+1. Launch & initialize Requestor `yagna` daemon
+2. Launch Requestor Agent to start an interactive service payload on a VM 
+3. Execute a simple ExeScript batch to ensure successful interaction with payload
+4. Disconnect the Requestor machine from network
+5. Reconnect the Requestor machine to network
+6. Execute a simple ExeScript batch to ensure the Requestor Daemon has successfully reconnected
+
+### 1.4. Requestor Daemon network address change
+1. Launch & initialize Requestor `yagna` daemon on machine with IP address A
+2. Launch Requestor Agent to start an interactive service payload on a VM 
+3. Execute a simple ExeScript batch to ensure successful interaction with payload
+4. Shutdown the Requestor Daemon
+5. Start the Requestor Daemon with the same node id/identity on a different IP address
+6. Execute a simple ExeScript batch to ensure the Daemon has successfully reconnected from a different network address
+
+
+## 2. Requestor offline ("fire&forget") 
+
+### 2.1. Upfront payment
+1. Launch & initialize Requestor `yagna` daemon
+2. Launch Requestor Agent to start an interactive service, with upfront payment allowing for `t` seconds of operation
+3. Ensure the service runs successfully (eg. by observing logs on Provider)
+4. Shutdown the Requestor Agent & Daemon
+5. Ensure the service runs successfully on provider
+6. Wait `t` seconds
+7. Ensure the Provider has terminated the Activity after the budget runs out
+
+### 2.2. Self-sustained payment
+1. Launch & initialize Requestor `yagna` daemon
+2. Launch Requestor Agent to start an interactive service, with self-sustained payment platform
+3. Ensure the service runs successfully (eg. by observing logs on Provider)
+4. Shutdown the Requestor Agent & Daemon
+5. Ensure the service runs successfully on Provider
+6. Restart the Requestor Agent & Daemon
+7. Terminate the Activity
+
+## 3. Requestor delegates control
+
+### 3.1. Full control delegation
+1. Launch & initialize Requestor `yagna` daemons A & B
+2. Launch Requestor Agent on Requestor A to start an interactive service, with pay-as-you-go payment scheme
+3. Execute a simple ExeScript batch from Requestor A to ensure successful interaction with payload
+4. Grant control over the Agreement to Requestor B
+5. Launch Requestor Agent on Requestor B 
+6. Execute a simple ExeScript batch from Requestor B to ensure successful interaction with payload
+7. Terminate the Activity from Requestor B
+
+### 3.2. Partial control delegation
+...basically run scenarios as in 3.1., but granting various atomic permissions and validating that respective actions are permitted/forbidden accordingly.
+