Implement AbandonStagedChanges Dance

[evomimic]

Summary

This enhancement adds the _abandon_staged_changes_ dance to the Uniform API. This dance marks a staged_holon as Abandoned . Staged holons marked Abandoned are simply ignored during commit processing -- they are not saved to the persistent store. Once a staged_holon has been abandoned, further attempts to access the holon will return a (newly introduced) NotAccessible error.

Current State:

There is no native functionality that supports this function.

However, some existing native functionality needs to modified:

• we cannot simply remove an abandoned holon from the CommitManager's staged_holons vector, because that could affect the position of other holons in the vector and StagedIndex depends upon vector position.
• the current definition of CommitResponse assumes that a holon commit either fails or results in a saved holon. On an 'Ok' result is returned the holon is added to the saved_holons vector. To make the semantics clearer, saves should be distinguished from abandons, even though both will return an Ok Result.
• we need to block attempts to access abandoned staged holons. One design option for this is to have each function assume responsibility for including a access guard. Another option is to move accessibility checks to a separate layer (perhaps as part of a "validation check" that is invoked by the dancer. This provides a more modular design and decreases the possibility of a developer "forgetting" to add a guard to a function. For now, this enhancement request is proposing the first option. We can move to the second option in the future as part of a _dancevalidation step (perhaps following the Decorator pattern).

Proposal

Enhance Native Holons Functionality

_In the holon_error.rs file within the Holons zome:_

• [x] Add a new NotAccessible error to the HolonError enum to report access violations

    #[error("{0} access not allowed while holon is in {1} state")]
    NotAccessible(String, String),

In the holon.rs file within the Holons zome:

• [x] Add an Abandoned variant to HolonState and extend the implementation of the fmt function to cover this variant
• [x] Add an abandon_staged_changes method that sets holon's state to Abandoned
• [x] Enhance the commit method to support Abandoned semantics.
• [x] Add an is_accessible(access_type: AccessType)->Result<_,HolonError> helper function, where

  pub enum AccessType {
  Read,
  Write,
  }

This function should return Ok if the requested access_type is allowed given the current state of the holon. Otherwise, return a NotAccessible error.

 - If requested access_type is `Read`, return true if and only if the holon's state is: `New`, `Fetched`, `Changed`, or `Saved`
 - If requested access_type is `Write`, return true if and only if the holon's state is: `New`, `Fetched`, or `Changed`,

• [x] Add "guards" to the following methods. A Read Guard refers to a call on is_accessible(Read) and a Write Guard_ refers to a call on is_accessible(Write).
  • [x] get_property_value -- Read Guard
  • [x] get_key -- Read Guard
  • [x] get_id -- Read Guard
  • [x] with_property_value -- Write Guard
  • [x] add_related_holons (on staged_reference.rs) -- Write Guard

_In the staged_reference.rs file within the Holons zome:_

• [x] Add an abandon_staged_changes method that gets a borrowed mut reference to its holon and then delegates the call to it.

_In the commit_manager.rs file:_

• [x] Enhance to_staged_reference to return a NotAccessible error on attempts to get a StagedReference from a StagedIndex if the referenced holon is in an Abandoned state.

• [x] Enhance the definition of CommitResponse to reflect the possible presence of Abandoned.

  pub struct CommitResponse {
        pub status: CommitRequestStatus,
        pub commits_attempted: MapInteger,
        pub saved_holons:Vec<Holon>,
        pub abandoned_holons: Vec<Holon>, // <=== NEW
    }

• [x] Enhance the commit() method's handling of the result of each holon's commit to add the Holon to the appropriate vector in the CommitResponse.

Dance Enhancements

_In the holon_dance_adapter.rs file:_

• [x] Define and implement a new "abandon_staged_changes" dance adapter function. Since abandon_staged_changes is a mutator, it's DanceRequest should be of type Command with its staged_holon's index passed via the Command's StagedIndex element. It should delegate the call to the StagedReference's abandon_staged_changes method

/// *DanceRequest:*
/// - dance_name: "abandon_staged_changes"
/// - dance_type: Command(StagedIndex) -- references the staged holon whose changes are being abandoned
/// - request_body: None
///   
///
/// *ResponseBody:*
/// - an Index into staged_holons that references the updated holon.
///

• [x] Implement build_abandon_staged_changes_dance_request as a CommandMethod

In the dancer.rs file:

• [x] Add "abandon_staged_changes" dance to the Dancer's dispatch table
• [x] Add error message for NotAccessible to the process_dispatch_result function.

_In the dance_response.rs file:_

• [x] Map the NotAccessible HolonError to BadRequest to the From<HolonError> for ResponseStatusCode implementation

Testing Enhancements

New files:

• [x] Add "test_abandon_staged_changes" test step executor

_In the test_data_types.rs file:_

• [x] Add AbandonStagedChanges as a variant in the DanceTestStep enum definition
• [x] add its fmt::Display implementation
• [x] Implement an `add_abandon_staged_changes" function

_In the dance_fixture.rs file:_

• [ ] Define a new abandon_staged_changes test case.
  • [x] Stage three holons (Book: h1, Person: h2, Person: h3)
  • [x] Give all three a property or two
  • [x] Add "AUTHORS" relationship from h1 to h2 and h3
  • [x] Abandon h2
  • [x] Attempt "with_properties" dance on h1 and h2 -- expect success on h1 and for h2 BadRequest/NotAccessible response
  • [x] Attempt "add_related_holon" from h2 to h3 -- expect a BadRequest/NotAccessible response
  • [x] Commit -- expect h1, h3 to have been saved, but not h2
  • [ ] Abandon h1, expect BadRequest/NotAccessible -- you can't abandon changes after they have been saved.
  • [x] Stage two holons (h4, h5)
  • [x] Give them some properties and relationships
  • [x] Abandon h4 and h5
  • [x] Commit -- expect zero saved

_In the dance_tests.rs file:_

• [x] Add a match that executes the AbandonStagedChanges step

Definition of Done:

• [x] The abandon_staged_holons_test, test case passes

[dauphin3]

@evomimic What is the associated ResponseStatusCode for HolonError::NotAccessible

[evomimic]

@evomimic What is the associated ResponseStatusCode for HolonError::NotAccessible

NotAuthorized

[dauphin3]

@evomimic What is the associated ResponseStatusCode for HolonError::NotAccessible

NotAuthorized @evomimic confirm: 401 - Unauthorized

I also see in the issue checklist, under dance_response.rs file it says to map to BadRequest, should it instead be Unauthorized? Is spelling correct or should the A be capital?

[evomimic]

Yea. I noticed that also after sending my reply. Probably BadRequest is better. NotAuthorized typically refers to a permissions issue.

[dauphin3]

@evomimic how to ensure relationship is populated?

[evomimic]

@dauphin3 : Hmmm... right. I don't think that will be possible until we implement #84. Currently, holon's try_from_node function is not loading the relationship_map (and we probably don't want to until we have RelationshipDescriptor's to guide the process). So there is not currently any way to tell which relationships have been populated.

Recommendation: Skip the relationship match.

• I've revised the task list above so that the Commit test step just confirms the proper holons have been saved, but does not do any matches on relationships.
• I've added the following task to Issue #84 : _"Enhance the _abandon_stagedchanges test case to use get_relatedholons to ensure relationships that are expected to have been populated on commit ARE populated and relationships that are NOT expected to have been populated have NOT been populated."