moat-kv 0.71.0__py3-none-any.whl → 0.71.7__py3-none-any.whl

docs/source/acls.rst

@@ -1,80 +0,0 @@
-==============
-Access control
-==============
-
-MoaT-KV employs a two-step access control scheme.
-
-First, you define an ACL hierarchy which controls which items may be
-accessed using a particular named ACL. Then you associate that ACL
-with users that shall be bound by it.
-
-
-ACLs
-====
-
-An ACL entry controls these access modes:
-
-* a: acl: retrieve the ACL flags for this node
-* r: read: retrieve the data at this node
-* w: write: change the data at this node
-* c: create: add new data to this node
-* d: delete: remove the data at this node
-* x: access: read specific sub-nodes below this one
-* e: enumerate: list sub-nodes of this one
-* n: new: create new nodes below this one
-
-In the MoaT-KV sources you'll also encounter these modes in calls to
-``follow_acl`` (i.e. these flags can be checked for but you cannot set
-them):
-
-* W: check 'c' if the node is new or has no data, else 'w'
-
-ACLs can use wildcards '+' (one level) and '#' (one or more levels).
-Search is depth-first; more specific keys are checked first.
-
-
-Association
-===========
-
-You change a user's ACL entry by adding an "acl=ACLNAME" field to the
-user's aux data. The user is affected as soon as they log back in.
-
-Updated ACL records are effective immediately.
-
-
-Putting it all together
-=======================
-
-Given the following data structure, the user "aclix" will only be able to
-write initial data to ``one`` and ``one two``. They can also read the data
-back. However, any other access is not possible::
-
-    null:
-      auth:
-        _:
-          current: _test
-        _test:
-          user:
-            aclix:
-              _:
-                _aux:
-                  acl: foo
-            std:
-              _:
-                _aux: {}
-      acl:
-        foo:
-          one:
-            _: rxnc
-            two:
-              _: rc
-    one:
-      _: 10
-      two:
-        _: 11
-    
-
-The above is the server content at the end of the testcase
-``tests/test_feature_acls.py::test_81_basic``, when
-dumped with the command ``moat kv : get -rd_``.
-

docs/source/auth.rst

@@ -1,84 +0,0 @@
-=========================
-MoaT-KV and authentication
-=========================
-
-MoaT-KV ships with a couple of rudimentary auth modules.
-
-The server's initial message lists the accepted authentication methods
-(``auth`` entry).
-
-Depending on the server version, auth requests may be answered with a
-stream even if the method doesn't actually require it. Login is successful
-if the reply (or stream-end message) doesn't contain an error.
-
-Included user auth methods
-==========================
-
-root
-----
-
-No access control. There is one possible user named "*"::
-
-    <<< {'seq': 0, 'version': (0, 58, 12), 'node': 'dev', 'auth': ('root',), …}
-    >>> {'typ': 'root', 'ident': '*', 'action': 'auth', 'seq': 1}
-    <<< {'state': 'start', 'seq': 2, 'wseq': 1, 'tock': 123}
-    <<< {'state': 'end', 'seq': 2, 'wseq': 2, 'tock': 124}
-
-password
---------
-
-This is the standard "username plus password" method. Passwords are hashed
-and salted on the server; transmission of the cleartext password is
-protected with a separate shared secret (Diffie-Hellman).
-
-This method currently is a bit slow, unless you use test mode (in which
-case it's a bit insecure).
-
-The client initiates a Diffie-Hellman handshake if required, then wraps the
-SHA256 of the password in a ``SecretBox`` (using a random nonce) and sends
-that to the server. Logging in as ``root``::
-
-    <<< {'seq': 0, 'version': (0, 58, 12), 'node': 'dev', 'auth': ('password',), …}
-    >>> {'pubkey': b'[256 bytes]', 'length': 1024, 'action': 'diffie_hellman', 'seq': 1}
-    <<< {'pubkey': b'[256 bytes]', 'seq': 1, 'tock': 999}
-    >>> {'typ': 'password', 'ident': 'root', 'password': b'[data]', 'action': 'auth', 'seq': 2}
-    <<< {'state': 'start', 'seq': 2, 'wseq': 1, 'tock': 1001}
-    <<< {'state': 'end', 'seq': 2, 'wseq': 2, 'tock': 1002}
-
-_test
------
-
-This is a test method that's suitable for experiments and testing.
-
-Users do not have a password.
-
-
-API
-===
-
-The authorization code is modular. MoaT-KV allows loading multiple auth
-methods, one of which is active. A method may use more than one record type
-(think "user" or "group"). Each of those records has a name.
-
-The "user" type is only special because server and client use that to
-process login requests.
-
-Multiple distinct MoaT-KV domains or subdomains are possible, by adding an
-additional meta-root record anywhere in the entry hierarchy.
-
-
-.. module:: moat.kv.auth
-
-.. autofunction:: loader
-
-.. autoclass:: BaseServerAuth
-   :members:
-
-.. autoclass:: BaseClientAuth
-   :members:
-
-.. autoclass:: BaseServerAuthMaker
-   :members:
-
-.. autoclass:: BaseClientAuthMaker
-   :members:

docs/source/client_protocol.rst

@@ -1,456 +0,0 @@
-========================
-MoaT-KV's client protocol
-========================
-
-MoaT-KV's native client protocol is based on MsgPack. The client sends
-requests; the server sends one or more responses. You may (and indeed
-should) run concurrent requests on the same connection.
-
-Strings must be UTF-8, as per MsgPack specification.
-
-Requests and replies are mappings.
-
-The server initially sends a greeting, using sequence number zero. It will
-not send any other unsolicited message.
-
-Requests
-========
-
-Client requests are always mappings. ``seq`` and ``action`` must be
-present. All other fields are request specific. The server will ignore
-fields it doesn't understand.
-
-seq
----
-
-Every client request must contain a strictly increasing positive sequence
-number. All replies associated with a request carry the same sequence
-number.
-
-action
-------
-
-The action which the server is requested to perform. Valid actions are
-described below.
-
-nchain
-------
-
-This field tells the MoaT-KV server how many change entries to return.
-The default is zero. If you want to update a value, retrieve the
-original with ``nchain`` set to one. Synchronization between MoaT-KV servers
-requires the number of possible partitions plus one, in order to protect
-against spurious conflict reports.
-
-path
-----
-
-The subset of data affected by the current command.
-
-
-Replies
-=======
-
-Server replies are always mappings. At least one of ``seq`` and ``error``
-must be present. The client must ignore fields it doesn't expect.
-
-seq
----
-
-The sequence number of the request which caused this reply.
-
-Server messages which don't include a sequence number are errors and
-will close the connection.
-
-The server will either send exactly one reply with any given sequence number,
-or a multi-reply sequence which starets with a ``state=start`` message.
-
-error
------
-
-This field contains a human-readable error message. A request has failed if
-this field is present.
-
-value
------
-
-The value of the MoaT-KV entry, assuming one was requested.
-
-state
------
-May be ``start`` or ``end``
-
-* ``start`` indicates the beginning of a multi-value result.
-
-* ``end`` indicates that a multi-value result has finished. No more
-  messages with this sequence number will be sent.
-
-The ``start`` message will contain neither an error nor a value.
-
-chain
------
-
-The change chain resulting from, or retrieved by, a command.
-
-Change chains track which server last modified a value, so that replayed
-updates can be ignored and conflicting updates can be recognized. A chain
-never contains any one MoaT-KV server more than once.
-
-See the server protocol for a detailed description.
-
-tick
-----
-
-The current server's change counter. This field can be used to ensure that
-the local server is not restarted with old state.
-
-tock
-----
-
-An always-increasing integer that's (supposed to be) shared within the
-whole MoaT-KV system. You can use it when you need to reconnect to a server,
-to make sure that the system is (mostly) up-to-date.
-
-path
-----
-
-The subset of data described by the current message.
-
-depth
------
-
-
-
-Actions
-=======
-
-connect
--------
-
-This is a pseudo-action with sequence number zero, which the server assumes
-to have received after connecting. The server's first message will contain
-``seq=0``, its ``node`` name, a ``version`` (as a list of integers), and
-possibly its current ``tick`` and ``tock`` sequence numbers.
-
-The ``auth`` parameter, if present, carries a list of configured
-authorization methods. The first method in the list **should** be used to
-authorize the client. If the list's first entry is ``None`` then
-authorization is not required. Other entries **may** be used for
-testing after a client is logged in.
-
-Sample::
-
-    >>> {'seq': 0, 'version': (0, 58, 12), 'node': 'dev', 'tick': 350225, 'tock': 558759182, 'qlen': 10, 'auth': ('password',)}
-
-auth
-----
-
-Tell the server about your identity. This method **must** be sent first, if
-the server requests authorization.
-
-The ``identity`` parameter tells the server which user ID (or equivalent)
-to use for logging in. ``typ`` contains the auth type to use; this
-**must** be identical to the first entry in the ``connect`` reply's
-``auth`` parameter.
-
-If this is not the first auth message, the authorization is verified but the
-resulting user identity is ignored.
-
-Example::
-
-    >>> {'typ': 'password', 'ident': 'root', 'password': b'[data]', 'action': 'auth', 'seq': 2}
-    <<< {'seq': 2}
-
-test_acl
---------
-
-Check whether the given ``path`` is accessible with the given  ``mode``.
-
-The ``acl`` to test may be specified. The user's ACL, if any, is also
-tested; the return message's ``access`` element may contain ``False``
-(access not allowed), ``True`` (access allowed but no ACL details
-available) or the actual ACL characters.
-
-Access will not be granted if you try to check a specific ACL when your
-own rights don't include 'a' (for accessing ACLs).
-
-stop
-----
-
-Send this action to abort a running multi-value request. Set ``task`` to
-the sequence number of the request to abort.
-
-This action only works after you received a ``start`` state message.
-It returns a :class:`bool` which is ``True`` if the command was still
-running.
-
-A positive reply does not indicate that no more messages with the stated
-sequence number will arrive; this will be indicated by the ``state=end``
-message.
-
-get_value
----------
-
-Retrieve a single value.
-
-If the value does not exist or has been deleted, you'll get ``None`` back.
-
-Alternately, you can set ``node`` and ``tick``, which returns the entry
-that has been set by this event (if the event is still available). The
-entry will contain the current value even if the event has set a previous
-value.
-
-Example::
-    >>> {'path': P('test.one'), 'action': 'get_value', 'seq': 4}
-    <<< {'value': 'Two', 'tock': 12345, 'seq': 4}
-
-set_value
----------
-
-Set a single value. The ``path`` to that ``value`` needs to be sent as a list.
-
-If you are updating a known value, you should send a ``chain`` entry
-to help ensure that no other node has changed it unexpectedly. (Of course,
-due to the distributed nature of MoaT-KV, this may happen anyway.) You can
-also use ``prev`` to send an expected old value, but you really shouldn't.
-
-This action returns the node's new change ``chain``. If you did not send a
-``chain`` field, the previous value is returned in ``prev``.
-
-Simple example::
-
-    >>> {'path': P('test.one'), 'value': 'Three', 'action': 'set_value', 'seq': 5}
-    <<< {'changed': True, 'tock': 12348, 'seq': 5}
-
-However, this is not particularly safe if you want to modify a value, as
-there's no way to ascertain that it hasn't been changed by somebody else in
-the meantime. It's safer to retrieve the entry's change log, or at least
-its first couple of entries, and then send that along with the
-``set_value`` request::
-
-    >>> {'path': P('test.one'), 'nchain': 3, 'action': 'get_value', 'seq': 4}
-    <<< {'value': 'Three', 'chain': {'node': 'r-a', 'tick': 121, 'prev': None}, 'tock': 12355, 'seq': 4}
-    >>> {'path': P('test.one'), 'value': 'Four', 'nchain': 3, 'chain': {'node': 'r-a', 'tick': 121, 'prev': None}, 'action': 'set_value', 'seq': 5}
-    <<< {'changed': True, 'chain': {'node': 'dev', 'tick': 69, 'prev': {'node': 'r-a', 'tick': 121, 'prev': None}}, 'tock': 12358, 'seq': 5}
-
-The ``chain`` value should be treated as opaque, except for``None`` which
-indicates that the node doesn't exist.
-
-delete_value
-------------
-
-Remove a single value. This is the same as setting it to ``None``. The
-``chain`` semantics of ``set_value`` apply.
-
-get_state
----------
-
-Retrieve the current system state. The following ``bool``-valued attributes
-may be set to specify what is returned. The corresponding reply is stored
-in an attribute of the same name.
-
-All of these data is mainly useful for debugging the replication / recovery
-protocol. The resulting lists can become somewhat long on a busy system.
-
-* nodes
-
-A dict of server ⇒ tick. Each server's known Tick values must be
-consecutive; when they are not, MoaT-KV tries to retrieve the missing
-entries.
-
-* deleted
-
-A dict of server ⇒ ranges of ticks known to have been deleted.
-
-* known
-
-A dict of server ⇒ ranges of ticks known. This contains current data as well
-as events that have been superseded.
-
-* current
-
-A dict of server ⇒ ranges of ticks corresponding to the current state of
-nodes. This is expensive to calculate. It is a superset of `'known``.
-
-* missing
-
-A dict of server ⇒ ranges of ticks not available on the server. This list is
-empty if the server thinks it is up-to-date.
-
-* remote_missing
-
-A dict of server ⇒ ranges of ticks reported to be missing at some other node.
-
-* present
-
-A dict of server ⇒ ranges of entries that actually exist.
-
-* superseded
-
-A dict of server ⇒ ranges of entries that have been replaced by a newer
-version of the corresponding node.
-
-get_tree
---------
-
-Retrieves all values with the prefix given in ``path``.
-
-This is a multi-value reply; each reply contains ``path`` and ``value``
-entries. Deleted nodes may or may not be reported.
-
-If the path does not exist or does not have children, a single-value reply
-is returned.
-
-Optimization: if a reply contains a "depth" key, its path is shortened by
-the request's path, plus that many elements from the previous reply's path.
-
-Thus, if you request a path of ``['a','b','c']``, this reply::
-
-    { seq=13, path=['a','b','c'], value="one" }
-    { seq=13, path=['a','b','c','d','e'], value="two" }
-    { seq=13, path=['a','b','c','d','f'], value="three" }
-
-is equivalent to::
-
-    { seq=13, depth=0, value="one" }
-    { seq=13, depth=0, path=['d','e'], value="two" }
-    { seq=13, depth=1, path=['f'], value="three" }
-
-* min_depth
-
-  Start reporting nodes at this depth.
-
-* max_depth
-
-  Limit recursion depth.
-
-* empty
-
-  Include empty nodes. This is useful when limiting the depth to non-leaf
-  nodes without data.
-
-root
-----
-
-Switch the client's root to the given path. This request returns the new
-root node.
-
-It is not possible to undo this request (other than to reconnect).
-Tasks started before this action are not affected.
-
-This action returns the new root node's value.
-
-watch
------
-
-Monitor changes to this node (and those below it). Replies look like those from ``get_tree``.
-
-The recommended way to run the ``watch`` call with ``fetch=True``. This
-fetches the current state and guarantees that no updates are lost. To mark
-the end of the static data, the server sends a ``state=uptodate`` message.
-This process will not send stale data after an update, so your code may
-safely replace an old entry's state with new data.
-
-This task obeys ``min_depth`` and ``max_depth`` restrictions.
-
-save
-----
-
-Instruct the server to save its state to the given ``path`` (a string with
-a filename).
-
-log
----
-
-Instruct the server to continuously write change entries to the given ``path``
-(a string with a filename). If ``fetch`` is ``True``, the server will also
-write its current state to that file.
-
-This command returns after the new file has been opened and the initial
-state has been written, if so requested. If there was an old log stream,
-there may be some duplicate entries. No updates are skipped.
-
-msg_send
---------
-
-Pass-through call to transmit a message. Parameters are ``type`` (the user
-event to send to) and ``data`` (the data to send).
-
-Raw binary data may be transmitted by using ``raw`` instead of ``data``.
-
-msg_monitor
------------
-
-Pass-through call to receive brodcast messages. You'll get a
-stream with ``data`` containing the decoded message. If decoding fails,
-``raw`` contains the message's bytes and ``error`` holds a string
-representation of the decoder problem.
-
-Set ``raw`` to True if the incoming messages are not supposed to be
-msgpack-encoded in the first place. In this case, ``data`` and ``error``
-will always be missing.
-
-Examples
-========
-
-You can turn on message debugging with 'moat -vvv kv'.
-
-Get and set a value
--------------------
-
-If the value is not set::
-
-    Send {'path': ('test',), 'nchain': 3, 'action': 'get_tree', 'seq': 1}
-    Recv {'value': None, 'seq': 1}
-
-Setting an initial value::
-
-    Send {'value': 1234, 'path': ('test',), 'nchain': 2, 'chain': None, 'action': 'set_value', 'seq': 2}
-    Recv {'changed': True, 'chain': {'node': 'test1', 'tick': 2, 'prev': None}, 'seq': 2}
-
-Trying the same thing again will result in an error::
-
-    Send {'value': 1234, 'path': ('test',), 'nchain': 2, 'chain': None, 'action': 'set_value', 'seq': 3}
-    Recv {'error': 'This entry already exists', 'seq': 3}
-
-To fix that, use the chain value you got when setting or retrieving the
-previous value::
-
-    Send {'value': 123, 'path': ('test',), 'nchain': 2, 'chain': {'node': 'test1', 'tick': 2}, 'action': 'set_value', 'seq': 4}
-    Recv {'changed': True, 'chain': {'node': 'test1', 'tick': 3, 'prev': None}, 'seq': 4}
-
-Sending no precondition would also work
-
-After you set multiple values::
-
-    Send {'value': 123, 'path': ('test', 'foo'), 'nchain': 0, 'action': 'set_value', 'seq': 5}
-    Recv {'changed': True, 'prev': None, 'seq': 5}
-    Send {'value': 12, 'path': ('test', 'foo', 'bap'), 'nchain': 0, 'action': 'set_value', 'seq': 6}
-    Recv {'changed': True, 'prev': None, 'seq': 6}
-    Send {'value': 1, 'path': ('test', 'foo', 'bar', 'baz'), 'nchain': 0, 'action': 'set_value', 'seq': 7}
-    Recv {'changed': True, 'prev': None, 'seq': 7}
-    Send {'value': 1234, 'path': ('test',), 'nchain': 0, 'action': 'set_value', 'seq': 8}
-    Recv {'changed': True, 'prev': 123, 'seq': 8}
-
-you can retrieve the whole subtree::
-
-    Send {'path': ('test',), 'nchain': 0, 'action': 'get_tree', 'seq': 1}
-    Recv {'seq': 1, 'state': 'start'}
-    Recv {'value': 1234, 'depth': 0, 'seq': 1}
-    Recv {'value': 123, 'path': ('foo',), 'depth': 0, 'seq': 1}
-    Recv {'value': 12, 'path': ('bap',), 'depth': 1, 'seq': 1}
-    Recv {'value': 1, 'path': ('bar', 'baz'), 'depth': 1, 'seq': 1}
-    Recv {'seq': 1, 'state': 'end'}
-
-Retrieving this tree with ``moat kv test get -rd ':val'`` would print::
-
-    test:
-      :val: 1
-      foo:
-        :val: 1
-        bap: {':val': 12}
-        bar:
-          :val: 1
-          baz: {':val': 1}
-
-