plesty.server.model.process
===========================

.. py:module:: plesty.server.model.process

.. autoapi-nested-parse::

   What the bench remembers and observes about a running device server.

   A :class:`ProcessRecord` is written when a server is launched and read by
   every later ``plesty-server`` process — the CLI, the agent, the GUI — so all
   of them see the same servers. A :class:`ProcessStatus` is what one of them
   concludes right now from the record, the process table and a protocol probe.



Attributes
----------

.. autoapisummary::

   plesty.server.model.process.STOPPED
   plesty.server.model.process.STARTING
   plesty.server.model.process.RUNNING
   plesty.server.model.process.EXITED
   plesty.server.model.process.STATES


Classes
-------

.. autoapisummary::

   plesty.server.model.process.ProcessRecord
   plesty.server.model.process.ProcessStatus


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

.. py:data:: STOPPED
   :value: 'stopped'


.. py:data:: STARTING
   :value: 'starting'


.. py:data:: RUNNING
   :value: 'running'


.. py:data:: EXITED
   :value: 'exited'


.. py:data:: STATES

.. py:class:: ProcessRecord

   What the supervisor persists about a started server.

   :ivar name: Device instance name.
   :ivar pid: Process id of the launcher that owns the server.
   :ivar port: TCP port it was told to bind.
   :ivar started_utc: ISO timestamp of the launch.
   :ivar command: The full command line.
   :ivar cwd: Working directory the server runs in.
   :ivar log: Path of the log file its output goes to.
   :ivar python: The interpreter — what a relaunch has to repeat.
   :ivar module: The ``python -m`` target — likewise.
   :ivar args: The spec's arguments — likewise.
   :ivar env: The spec's environment — likewise.
   :ivar package: Distribution the server runs, for listings.
   :ivar version: Its installed version, for listings.



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


   .. py:attribute:: pid
      :type:  int


   .. py:attribute:: port
      :type:  int


   .. py:attribute:: started_utc
      :type:  str


   .. py:attribute:: command
      :type:  list[str]


   .. py:attribute:: cwd
      :type:  str


   .. py:attribute:: log
      :type:  str


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



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



   .. py:attribute:: args
      :type:  list[str]
      :value: []



   .. py:attribute:: env
      :type:  dict[str, str]


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



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



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

      JSON form.



   .. py:method:: from_dict(data: collections.abc.Mapping[str, Any]) -> ProcessRecord
      :classmethod:


      Rebuild a record from :meth:`to_dict` output (extra keys ignored).



   .. py:method:: load(path: pathlib.Path) -> ProcessRecord | None
      :classmethod:


      Read a record file; ``None`` when absent or unreadable.



   .. py:method:: save(path: pathlib.Path) -> pathlib.Path

      Write the record to *path*; returns it.



.. py:class:: ProcessStatus

   The observed state of one device server.

   :ivar name: Device instance name.
   :ivar state: One of :data:`STATES`.
   :ivar pid: Process id when a record exists.
   :ivar port: Probed port when a record exists.
   :ivar started_utc: Launch time when a record exists.
   :ivar log: Log path when a record exists.
   :ivar returncode: Exit code for an ``exited`` server, when the launcher
                     recorded one (``-1`` when it vanished without).
   :ivar detail: For an exited server, the tail of its log — why it died.



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


   .. py:attribute:: state
      :type:  str


   .. py:attribute:: pid
      :type:  int | None
      :value: None



   .. py:attribute:: port
      :type:  int | None
      :value: None



   .. py:attribute:: started_utc
      :type:  str | None
      :value: None



   .. py:attribute:: log
      :type:  str | None
      :value: None



   .. py:attribute:: returncode
      :type:  int | None
      :value: None



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



   .. py:property:: alive
      :type: bool


      Whether the process exists (running or still starting).


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

      JSON form (what ``status`` prints and the agent returns).