Commit 0360b3b9 authored by Kyle Sunden's avatar Kyle Sunden

Merge branch 'hints' into 'master'

YEP-111: hints

See merge request !46
parents b576c8ee 60125986
Pipeline #197605608 passed with stage
in 42 seconds
---
yep: 111
title: Hints
author: Blaise Thompson <blaise@untzag.com>
status: draft
tags: standard
post-history: 2020-09-27
---
# 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](http://nsls-ii.github.io/bluesky/callbacks.html#hints).
# Table of Contents
[TOC]
# Motivation
Using Avro-RPC (see [YEP-107](https://yeps.yaq.fyi/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:
- what informational fields should be displayed?
- which fields can be set, and which are read-only?
- what messages are used to read and write a given field?
- which read-only fields are dynamic?
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:
- to change `dyanmic` from `true` to `false`
- to narrow the scope of a union type
# Discussion
Discussion can be found on the [gitlab issue](https://gitlab.com/yaq/yeps/-/issues/23) for this YEP.
# Copyright
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment