Reference

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

FieldTypeAnswers
viewsViewsQueries!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>RowFor a system machine: its instance at the view's key, or null before the host has started it.
<row>.idUUID!The instance's id.
<row>.<field>see belowOne 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 with FORBIDDEN before anything is read. Both are GraphQL errors whose extensions.code is 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.ViewRowLimit of 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 own get still 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 get checks it, at every read. A caller the view admits but the machine's rule refuses (an owner who lost a role the machine's read names) 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 status and order-status), and no two name one row type (pinned sticky reading note and pinned reading sticky-note are both PinnedStickyNoteRow). The glossary's and the host file's readers refuse a view that breaks either rule, so from-gherkin --check fails on it, naming the view. A field it shows is a GraphQL name (letters, digits and _, not starting with a digit or __) and is not id, which is the instance's. Any other name refuses the host with an InvalidOperationException naming 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 no views root, and refuses to start with an InvalidOperationException naming 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