Views root
Package Trax.Api.GraphQLSurface GraphQL schemaSource MachineViewTypeModule.cs, MachineViews.cs, ViewDocuments.cs
A host that serves machines from features
(ServeFeatures) serves each view its host.json declares
as a query field under views. A view shows fields of the machines it reads: the caller's own instances of a user
machine, and the one instance of a system machine at its key. Who may read a view is its readers, the actors the
features show reading it (feature files). The decision is
ADR 0058.
Members
| Field | Type | Answers |
|---|---|---|
views | ViewsQueries! | The views, on the query root only. There is no views field on a host that registers none. |
views.<view> | <View>View! | The view, for the caller. The field is the view's name in camelCase (shop sign is shopSign), its type the name in PascalCase with View after it (ShopSignView). |
views.<view>.<machine> | [<View><Machine>Row!]! | For a user machine: the caller's newest instances, at most ViewRowLimit of them, oldest first. The field is the machine's field under machines (v-order is vOrder). |
views.<view>.<machine> | <View><Machine>Row | For a system machine: its instance at the view's key, or null before the host has started it. |
<row>.id | UUID! | The instance's id. |
<row>.<field> | see below | One field per field the view shows of that machine, under the view's name for it. |
A field from a machine's state is a String: the state's label when the view gives labels for it, the state's
name otherwise. A field from a context field has the GraphQL type the machine's record gives that field, as on the
machine's own operations (Machines root).
A dictionary context field (an object whose values share one schema) arrives as a list of key and value pairs,
not as a JSON object: a field whose values are integers is [KeyValuePairOfNullableStringAndInt64!], each item
{ key value }. The key is a nullable String, so the client trax client generates types it key: string | null,
and the list itself is nullable.
Example
query {
views {
bookings { booking { id seat status } }
departures { flight { id status } }
}
}Behavior
- Who reads. A caller with no user key is refused with
UNAUTHENTICATED. A view whose readers are not anyone signed in is read by a caller in one role of every role set they name; anyone else is refused withFORBIDDENbefore anything is read. Both are GraphQL errors whoseextensions.codeis the code. - What is read. Only the caller's own instances (owner
user, with the caller's user key), and the system instance at the key the view names. Another user's instance is never in a view. - How many. A user machine's list is the caller's newest instances, by when each was created, at most
StateMachineOptions.ViewRowLimitof them (100 unless the host sets it), listed oldest first. An older instance is not in the view, and there is no paging argument; the machine's owngetstill reads it by id. - Each machine's read rule. A user machine the view reads holds the caller to its own read rule too, checked as
its
getchecks it, at every read. A caller the view admits but the machine's rule refuses (an owner who lost a role the machine'sreadnames) gets an empty list for that machine, not an error, and the rest of the view reads as usual. A system machine has no read rule of its own: its instance is read under the view's readers alone. - Names. A view's name is words of ASCII letters and digits split by spaces, hyphens or underscores, the first
starting with a letter. No two views fold to one PascalCase name (
order statusandorder-status), and no two name one row type (pinned stickyreadingnoteandpinnedreadingsticky-noteare bothPinnedStickyNoteRow). The glossary's and the host file's readers refuse a view that breaks either rule, sofrom-gherkin --checkfails on it, naming the view. A field it shows is a GraphQL name (letters, digits and_, not starting with a digit or__) and is notid, which is the instance's. Any other name refuses the host with anInvalidOperationExceptionnaming the view and the field when the schema builds. - Registration order. The machines directory, and with it the views, are registered before
AddTraxGraphQL(). A host that registers views after it has noviewsroot, and refuses to start with anInvalidOperationExceptionnaming them (registration order).
Persisted documents
With persisted operations on, the host
registers one document per view, selecting every field the view shows, so a host that requires persisted operations
serves its views with no upload. The id is trax_view_<view>_<shapeHash><textHash>, <view> being the view's field
under views, hashed as a train's documents are: a client built against one shape of a view is told
CLIENT_OUTDATED once the shape changes. The documents live under the null tenant, and the trax_view_ prefix is
reserved: upload, deactivate and restore refuse it (RESERVED_ID). The view's readers still decide who reads it;
the document only lets the host run it. A generated client finds each view's document under Views in the
client manifest.
See also
- Machines root: the machines a view reads, served as typed operations.
- Feature files: where a view and its readers come from.
- Error codes:
UNAUTHENTICATED,FORBIDDEN,CLIENT_OUTDATED.