plesty.server.model.agent

What this bench serves remote clients on: the agent’s own settings.

The agent had no configuration surface at all — endpoint, token and worker count came from plesty-server agent arguments and nowhere else, so a bench could only be made reachable from a command line, and was reachable only for as long as that command ran.

These settings belong to the bench, not to a fleet and not to the packaged module: two benches on one network need different tokens, and the same bench keeps its endpoint across whatever fleet is open. They live in the bench home as agent.yaml, beside the state the rest of the home holds.

The bench’s data path is kept here for the same reason: it is where this one bench writes on the lab’s shared disk, set once per bench in Server ▸ Configure…, and the same whichever fleet is open. A fleet only names folders under it (a device’s data_dir).

Attributes

`DEFAULT_BIND`
`DEFAULT_WORKERS`
`TOKEN_BYTES`
`ROLE_MASTER`
`ROLE_NODE`
`ROLES`
`DEFAULT_ROLE`
`DATA_ROOT_VAR`
`DATA_PATH_VAR`
`DEFAULT_DATA_DIR`
`DATA_SHARE_VAR`

Classes

AgentSettings

How the bench agent binds, whom it answers, and whether it drives others.

Functions

`check_data_location`(→ tuple[str, str])	Return share and folder, having made sure the bench can write in the folder.
`settings_file`(→ pathlib.Path)	Where home keeps the agent settings.
`load_agent_settings`(→ AgentSettings)	The agent settings of home, defaults when it has none.
`save_agent_settings`(→ pathlib.Path)	Write settings to home; returns the path.

Module Contents

plesty.server.model.agent.DEFAULT_BIND = 'tcp://*:5550'

plesty.server.model.agent.DEFAULT_WORKERS = 4

plesty.server.model.agent.TOKEN_BYTES = 24

plesty.server.model.agent.ROLE_MASTER = 'master'

plesty.server.model.agent.ROLE_NODE = 'node'

plesty.server.model.agent.ROLES

plesty.server.model.agent.DEFAULT_ROLE = 'node'

plesty.server.model.agent.DATA_ROOT_VAR = 'DEVICE_DATA_ROOT'

plesty.server.model.agent.DATA_PATH_VAR = 'DEVICE_DATA_PATH'

plesty.server.model.agent.DEFAULT_DATA_DIR = 'tmp'

plesty.server.model.agent.DATA_SHARE_VAR = 'PLESTY_DATA'

class plesty.server.model.agent.AgentSettings

How the bench agent binds, whom it answers, and whether it drives others.

Variables:

bind – ZMQ endpoint to bind.
token – Shared secret every exec/fetch must carry. Empty is legal and means no check — a bench on a network already trusted.
workers – Requests served concurrently.
role – master to drive other benches, node to serve only this one. One master to a group and no chaining, so the benches of a lab form a star: see is_master.
data_share – The Plesty share — the lab’s shared disk — as this machine mounts it (Z:/xyz/plesty, /Volumes/plesty). Empty until set.
data_folder – This bench’s folder in the share, relative to it (platform-a, any depth); empty for the share itself.
check_updates – Whether the console asks PyPI for a newer bench when it starts, at most once a day (#39).

bind: str = 'tcp://*:5550'

token: str = ''

workers: int = 4

role: str = 'node'

data_share: str = ''

data_folder: str = ''

check_updates: bool = True

property data_root: str

its folder in the share, where every device it starts writes.

Empty while no share is set.

Type:: The bench data path
Return type:: str

property guarded: bool

Whether a token is checked (never the token itself).

Return type:: bool

property is_master: bool

Whether this bench declares nodes and drives their devices.

A configuration convention rather than a permission: the agent checks one shared secret and knows no caller identity, so a node’s token drives that node whoever holds it, and nothing here stops a second bench from declaring itself master of the same nodes. What the role decides is what this console does — a node keeps no peer list and offers nothing remote.

Return type:: bool

validate() → AgentSettings

Return self, having refused settings the agent could not bind.

Raises:: FleetError – When the endpoint is empty or the worker count is not a positive number.
Return type:: AgentSettings

to_mapping() → dict[str, Any]

The document written to agent.yaml.

Return type:: dict[str, Any]

classmethod from_mapping(raw: Any) → AgentSettings

Read a document, falling back to the defaults key by key.

A settings file nobody can parse must not stop the console from opening: what is unreadable is replaced by its default rather than raised, since the operator can see and fix every value in the dialog.

Parameters:: raw (Any)
Return type:: AgentSettings

with_new_token() → AgentSettings

These settings with a freshly generated token.

Return type:: AgentSettings

device_data_env(name: str, data_dir: str | None, fallback: pathlib.Path | None = None) → dict[str, str]

Where a device the bench starts may write, and where it writes by default.

Parameters:

name (str) – The device, whose own folder under tmp is its default.
data_dir (str | None) – Its folder under the bench data path, as its declaration names it; None for tmp/<name>.
fallback (pathlib.Path | None) – Where it writes while the bench has no share — a folder of the bench’s own (#43). A device that must have a data path otherwise refused to start on a bench alone.

Returns:

DEVICE_DATA_ROOT, DEVICE_DATA_PATH and PLESTY_DATA — the share, which the device reports its folders relative to. Without a share, the first two under fallback and no PLESTY_DATA; nothing when there is no fallback either.

Return type:

dict[str, str]

run_data_env() → dict[str, str]

PLESTY_DATA for a run the bench starts: where it reads its devices’ files.

Return type:: dict[str, str]

plesty.server.model.agent.check_data_location(share: str, folder: str) → tuple[str, str]

Return share and folder, having made sure the bench can write in the folder.

An empty share is legal and means unset. Otherwise the share is an absolute path to an existing folder — a relative one would follow whatever directory a server happens to start in — and the bench’s folder is a path inside it, created when missing.

Returns:

The share, and the folder as a/b (empty for the share itself).

Raises:

FleetError – Naming why the bench cannot write there.

Parameters:

share (str)
folder (str)

Return type:

tuple[str, str]

plesty.server.model.agent.settings_file(home: plesty.server.model.home.Home) → pathlib.Path

Where home keeps the agent settings.

Parameters:: home (plesty.server.model.home.Home)
Return type:: pathlib.Path

plesty.server.model.agent.load_agent_settings(home: plesty.server.model.home.Home) → AgentSettings

The agent settings of home, defaults when it has none.

Parameters:: home (plesty.server.model.home.Home)
Return type:: AgentSettings

plesty.server.model.agent.save_agent_settings(home: plesty.server.model.home.Home, settings: AgentSettings) → pathlib.Path

Write settings to home; returns the path.

The file holds a shared secret, so it is made readable by its owner alone. Windows ignores the mode — there the bench home’s own ACL is the guard — which is why the token is a bench-network secret and not a credential.

Raises:

FleetError – When the settings would not bind (see AgentSettings.validate()).

Parameters:

home (plesty.server.model.home.Home)
settings (AgentSettings)

Return type:

pathlib.Path