Skip to main content

Pglet protocol

Pglet is a language-agnostic UI server which can be run locally, self-hosted in your local network or used as a hosted service.

One of the design goals of Pglet was comfort progress updates from CI/CD workflows, internal tools and scheduled jobs written in Bash and PowerShell, so the protocol had to be simple and fast.

The protocol is text-based and was partially inspired by Redis protocol.

Communication channel

Pglet client is used to establish a communication channel with Pglet service. Client is a part of pglet (or pglet.exe on Windows) executable which is automatically downloaded by a client library you use or can be downloaded manually from releases.

For every new connection to a page (pglet page <name>) or a new app session (pglet app <name>) Pglet client creates two FIFO named pipes on macOS/Linux or two named pipes on Windows:

  • Command pipe - bi-directional pipe for sending command requests and receiving responses.
  • Event pipe - read-only pipe with a constant stream of events (click, change, etc.) generated by a user.

Pglet client returns the name/path of command pipe and to get the name of event pipe append .events to a command pipe name.

Command messages

Request

Each request to a command pipe represents a single- or multi-line command in the format:

<command> [value_1] [value_2] ... [property_1=value] [property_2=value] ...

For example, command adding a new Text control to a page:

add text value="Hello, world!"

or adding multiple controls at once to a stack named footer:

add to=footer
  textbox id=firstName
  button id=cancel text=Cancel

Properties parsing is quite relaxed. If the value doesn't have spaces you can ommit quotes, for example text=Hello. Both single and double quotes can be used to enclose the value with spaces, for example: value="World's best coffee", or value='"quoted" text'. The following escape symbols are supported: \n, \t, \", \'.

Response

Successful response has the following format:

<number_of_additional_result_lines> [value]
result_line_1
result_line_2
...

For example, the result of get firstName value command reading the value property of firstName textbox might look like:

0 John Smith

If you are reading the value of multiline=true textbox then the result will look like:

2 First line
Second line
Third line

where 2 means "result has 2 more lines".

The response of commands non-returning any values is just 0 .

note

Certain commands may not have a response at all. These are fire-and-forget commands with the names ending on "f": addf, setf, appendf, cleanf, removef. Fire-and-forget commands are handy when you are quickly doing a lot of control modifications and don't care about the results, for example, updaing progress bar in a loop.

Events

Read event pipe to wait and receive events fired by users interacting with a web page.

Each event message is a single line in the format:

<event_target> <event_name> [event_data]

where <event_target> is ID of a control generated the event, <event_name> is event name, e.g. click, change and [event_data] is optional event data attached to a control with data property (usually, used with buttons).

For example, a serie of event might look like:

firstName change John
agreeTOS change true
ok click
cancel click
...