plesty.server.model.peer
========================

.. py:module:: plesty.server.model.peer

.. autoapi-nested-parse::

   The other benches this one drives: the master's node list.

   A bench declared ``role: master`` (:mod:`plesty.server.model.agent`) shows the
   devices of other benches beside its own and acts on them. Each of those benches
   is a :class:`Peer` — where its agent listens and the secret it checks.

   The list belongs to the *bench*, as the agent settings do, and not to a fleet:
   the nodes of a rig do not change because another fleet file was opened, and a
   node's declaration of a device is its own business. So it lives in the bench
   home as ``peers.yaml``, and a node never has one.

   Reading it is deliberately strict. A peer is a declaration, like a device: a
   key nobody recognises is a mistake worth a message, not a value to drop on the
   floor along with the address it was meant to carry.



Attributes
----------

.. autoapisummary::

   plesty.server.model.peer.PEERS_FILENAME
   plesty.server.model.peer.PEERS_VERSION
   plesty.server.model.peer.PEER_KEYS


Classes
-------

.. autoapisummary::

   plesty.server.model.peer.Peer


Functions
---------

.. autoapisummary::

   plesty.server.model.peer.peers_file
   plesty.server.model.peer.parse_peers
   plesty.server.model.peer.load_peers
   plesty.server.model.peer.save_peers


Module Contents
---------------

.. py:data:: PEERS_FILENAME
   :value: 'peers.yaml'


.. py:data:: PEERS_VERSION
   :value: 1


.. py:data:: PEER_KEYS

.. py:class:: Peer

   One bench this master drives.

   :ivar name: What the console calls it — the Host column's value, and unique
               among peers. Not required to be the node's hostname: a bench is
               named for the rig it runs, which is what an operator looks for.
   :ivar address: Where the node's agent listens: ``host``, ``host:port`` or a
                  full ZMQ endpoint. Resolved to an endpoint where it is used, so
                  that this model needs nothing of the client.
   :ivar token: The node's shared secret, or empty when it checks none.
   :ivar data: Where that bench sees the lab's shared data disk — the same disk
               every bench sees, each under its own path. Empty when unset.



   .. py:attribute:: name
      :type:  str


   .. py:attribute:: address
      :type:  str


   .. py:attribute:: token
      :type:  str
      :value: ''



   .. py:attribute:: data
      :type:  str
      :value: ''



   .. py:property:: guarded
      :type: bool


      Whether a secret is sent to this node (never the secret itself).


   .. py:property:: host
      :type: str


      The machine the bench runs on, without its agent's port or scheme.

      ``tcp://lab-bench-03:5550``, ``lab-bench-03:5550`` and ``lab-bench-03``
      are all ``lab-bench-03``: the device servers on that bench listen on
      their own ports of the same machine.


   .. py:method:: validate() -> Peer

      Return self, having refused a peer that could not be reached.

      :raises FleetError: When the name or the address is empty.



   .. py:method:: to_mapping() -> dict[str, Any]

      This peer's entry in the document, without its name.



   .. py:method:: from_mapping(name: str, raw: Any) -> Peer
      :classmethod:


      Build the peer *name* from its entry.

      :raises FleetError: When the entry is not a mapping or carries a key this
          version does not know.



.. py:function:: peers_file(home: plesty.server.model.home.Home) -> pathlib.Path

   Where *home* keeps the node list.


.. py:function:: parse_peers(document: Any) -> list[Peer]

   Every peer of a ``peers.yaml`` document, in the order it declares them.

   :raises FleetError: When the document, its ``peers`` key or any entry is
       malformed.


.. py:function:: load_peers(home: plesty.server.model.home.Home) -> list[Peer]

   The nodes *home* declares, empty when it declares none.

   :raises FleetError: When the file cannot be read or is malformed. A master
       whose list is broken is told so — an empty table would say the
       nodes are gone, which is a different thing entirely.


.. py:function:: save_peers(home: plesty.server.model.home.Home, peers: list[Peer]) -> pathlib.Path

   Write *peers* to *home*; returns the path.

   The file holds the nodes' shared secrets, so it is made readable by its
   owner alone — the same guard, and the same Windows caveat, as the agent's
   own settings.

   :raises FleetError: When a peer is incomplete or two share a name.