1  #+TITLE: Story 24 - Keeper
  2  #+AUTHOR: Le’
  3  #+OPTIONS: date:nil
  4  #+LANGUAGE: en
  5  #+CATEGORY: core
  6  
  7  This is a deeper dive into the ideas in [[file:story-23-Storage.org::+TITLE: Story 23 - Storage][story 23 - Storage]], focusing
  8  on designing *Stored Object handling*.
  9  
 10  * Stored Object handling - the *Keeper*
 11  
 12  Through all my earlier ruminations, one thing was clear, it was necessary
 13  to have an /Operation/ for *Stored Object handling*.  The difficulty was to
 14  understand how it would relate to the /Objects/ themselves, as well as to a
 15  *Store*, or where it would have to be associated, and in that case, with
 16  what?
 17  
 18  A though is that one can make the /Operation/ to handle *Stored Objects*
 19  can be separated from the *Store*.  All this /Operation/ needs is the
 20  *Storage Reference* and the /Object/ it's handling.
 21  
 22  This /Operation/ is meant to be associated with an /Object/, or has an
 23  assigned /Object/.  It means that it should be possible to get an associated
 24  *Keeper* from an /Object/, and it should be possible to get an assigned
 25  /Object/ from a *Keeper*.  In fact, this is a bi-directional association,
 26  forming a sort of symbiosis.
 27  
 28  ** Nomenclature
 29  
 30  This Operation needs a noun and a verb
 31  
 32  *Keeper* and *Keep* / *Kept*
 33  
 34  This means that the C type is likely to be ~LSC_keeper_t~.
 35  
 36  Some function names will have to be watched so they don't give the
 37  wrong idea.  For example, the way to link an Object to an Operation
 38  is usually named ~LSC_use_{operation-noun}_{object-noun}~, but the
 39  name ~LSC_use_keeper_key~ would probably give the wrong idea.
 40  An idea to get the idea across is have a nomenclature related to
 41  /assignment/ rather than /use/.
 42  
 43  ** Identification and registration
 44  
 45  A *Keeper* implementation is identified by name, just like cryptographic
 46  algorithm implementations.
 47  
 48  A *Keeper* implementation is /Object/ class specific.  This means that a
 49  *Keeper* for the *Key* Object would be separate from a *Keeper* for another
 50  Object class.
 51  
 52  This also means that there would be separate registries for each /Object/
 53  class that *Keepers* are meant to support.
 54  
 55  ** Funcionality
 56  
 57  *Keeper* Functions:
 58  
 59  - Start Keeper ::
 60  
 61    This function is given a passphrase callback.  A session pointer /may/ be
 62    passed both ways, if relevant (a session could be relevant to share
 63    between multiple *Keepers* from the same plugin).
 64  
 65    This function is optional, but if it's implemented, it /must/ be called
 66    before any other interaction with the *Keeper*.
 67  
 68  - Stop Keeper ::
 69  
 70    This stops the *Keeper*.
 71    A session pointer /may/ be passed both ways, if relevant (a session could
 72    be relevant to share between multiple *Keepers* from the same plugin).
 73  
 74    This function is optional, but if it's implemented, it /must/ be called to
 75    end a keeper session.
 76  
 77  - Assign Object ::
 78  
 79    Assigns an /Object/ for the *Keeper* /Operation/ to handle.
 80  
 81    When the *Keeper* /Operation/ is an /Object/ associated /Operation/, the
 82    /Object/'s *Keeper* getter should call this function to assign the
 83    associated /Object/.
 84  
 85    This function should return an error if it doesn't know the /Object/
 86    intimately.
 87  
 88    Ideas for function names:
 89  
 90    -  ~LSC_assign_{object-noun}~
 91    -  ~LSC_keep_{object-noun}~
 92  
 93  - Deassign Object ::
 94  
 95    Forget the /Object/ that the *Keeper* /Operation/ handles.
 96  
 97    Ideas for function names:
 98  
 99    -  ~LSC_deassign_{object-noun}~
100    -  ~LSC_lose_{object-noun}~
101  
102  - Get Assigned Object ::
103  
104    Returns the /Object/ that the *Keeper* /Operation/ handles.
105  
106    Ideas for function names:
107  
108    -  ~LSC_get_kept_{object-noun}~
109  
110  - Load Kept Object ::
111  
112    Loads an /Object/ payload from a given *Storage Reference*.  Any
113    previously assigned /Object/ is deassigned and dropped.
114  
115    Ideas for function names:
116  
117    -  ~LSC_load_kept_{object-noun}~
118  
119  - Store Kept Object ::
120  
121    Stores the /Object/ payload and return the resulting *Storage Reference*.
122  
123    Ideas for function names:
124  
125    -  ~LSC_store_kept_{object-noun}~
126  
127  - Remove Kept Object ::
128  
129    Removes the /Object/ at a given *Storage Reference*.  No actual /Object/
130    needs to have been loaded beforehand.
131  
132    Ideas for function names:
133  
134    -  ~LSC_remove_kept_{object-noun}~
135  
136  - Parameter functionality ::
137  
138    The *Keeper* should be able to accept and return parameter values
139    associated with the /Object/.  For example, an ~LSC_key_t~ could have an
140    associated friendly name (however, perhaps those should be associated with
141    the ~LSC_key_t~ itself...  implementations will have to decide).
142  
143  ** Object serialised as Storage Reference
144  
145  With the functionality described above, the *Storage Reference* could also
146  be the serialized form of the /Object/, for example an appropriate =data:=
147  URI.