yaq-yeps/111


Hints

Abstract

This YEP describes a hints system for the yaq ecosystem. Using hints, yaq daemons provide suggestions for how clients might best display the daemon protocol. Hints are especially useful when automatically building graphical user interfaces. Hints are inspired in-part by the hinting system within bluesky.

Table of Contents

Motivation

Using Avro-RPC (see YEP-107), yaq daemons completely specify their client interface. A client knows the exact signature of every message that the daemon supports. In addition, yaq has a traits system that clients can use when they expect certain basic behaviors. Still, it can be difficult to automatically construct "rich" clients, especially graphical user interfaces, for a given yaq daemon.

A typical graphical client needs to know the following:

Here "field" is a single piece of information about a daemon, things like "current position", "integration time", and "averaging method". Because individual daemons are allowed to specify arbitrary messages beyond those implied by traits, it can be a challenge to automatically discover the relevant fields for an arbitrary daemon. The hints system allows daemons to help connected clients by specifing relevant fields.

Hints exist on-top-of and do not modify or define the Avro-RPC protocol which each daemon defines. Clients may ignore hints without penalty.

Specification

Hints appear under the hints key of every schema provided by yaq daemons. This key maps to a string: record mapping where the string key is the field name and the record matches the following:

{
  "type": "record",
  "name": "field",
  "fields": [
    {"name": "getter", "type": "string"},
    {"name": "setter", "type": ["null", "string"], "default": "null"},
    {"name": "dynamic", "type": "boolean", "default": true},
    {"name": "type", "type": "string"}
}

The strings getter and setter are the message names used to get and set that field.

The getter message must accept no required arguments and must return exactly the type specified. Every hint must have a getter.

The setter message must accept exactly one required argument of the type specified. If a hint does not have a setter it is assumed read-only.

dyanamic indicates whether a read-only field's value can change while the daemon is running. Any non read-only hint is assumed to be dynamic.

type is a valid Avro type. It is encouraged to use simple types here, as most graphical clients may not be able to display arbitrarily complex types.

Hints may be specified by traits. Individual daemons may overload trait-specified hints, but only in the following cases:

Discussion

Discussion can be found on the gitlab issue for this YEP.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.


built 2020-10-03 01:33:36                                      CC0: no copyright