liza/doc/client.texi

@c  This document is part of the Liza Data Collection Framework manual.
@c  Copyright (C) 2017 R-T Specialty, LLC.
@c
@c    Permission is granted to copy, distribute and/or modify this document
@c    under the terms of the GNU Free Documentation License, Version 1.3
@c    or any later version published by the Free Software Foundation;
@c    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
@c    Texts.  A copy of the license is included in the section entitled ``GNU
@c    Free Documentation License''.

@node Client
@chapter Client
@maintstart
@footnote{
  The client is largely managed by a single class,
    @srcref{src/client/Client.js, Client},
    which has grown out of control.
  @code{Client} mediates essentially the entire system.
  Code is to be extracted out of this class as it is touched.

  The other system mammoth is @code{Ui} (@pxref{Program UI}).}
@maintend

@helpwanted

@menu
* Error Handling::
* Saving to Server::  Posting bucket diff to the Server.
@end menu


@node Error Handling
@section Error Handling

@maintenance{
  The complexity of this system and integration into legacy
    layers has caused maintenance trouble in the past.
  Each of the error checking layers need to be integrated
    to reduce complexity.}

@cindex Error
@cindex Failure
There are three layers of error checking:@footnote{
  Primarily for legacy reasons.
  They are being consolodated as the system is touched.}

@enumerate
  @item Required field checking@mdash{
    }whether all required questions have been answered.
  @item Type Validation@mdash{
    }verify that questions contain valid data according to their
    declared type. @ref{Validation}.
  @item Assertions@mdash{
    }arbitrary checks on data.
    @ref{Assertions}.
@end enumerate

@cindex Required Field
@cindex Field, Required
@cindex Field, Fixed
@cindex Error, Fixed
@cindex Error, Required
@cindex Fixed, Error
Required fields fail serially@mdash{
  }the system will notify the user of the required field,
    and direct him/her to it (usually through scrolling).
A field is marked as @dfn{fixed} according to the rules
  in @ref{Managing Error State}.


@menu
* Managing Error State::  Determining when failures should be marked as ``fixed''
@end menu


@node Managing Error State
@subsection Managing Error State

@cindex Failure Stack
@cindex Error Stack
Each failure caused by assertions is associated with a
  @dfn{failure stack}.
The stack represents the trail of assertions that have run,
  containing the ids of all values asserted against.
When any field or classification changes that is represented on the
  failure stack,
    the failure for the failed field associated with that failure stack
    is cleared.

@exnotice{
  If an assertion for some question @var{foo} first checked the value
    of bucket field @var{bar},
    and within its failure checked the value @var{c:predicate},
    the failure stack would contain both of those ids.
  If either @var{bar} or the @var{predicate} classification changed,
   the question @var{foo} would have its error cleared.}

Error state is managed by
  @srcref{src/validate/ValidStateMonitor.js, ValidStateMonitor}.



@node Saving to Server
@section Saving to Server
@helpwanted

@cindex Saving
@cindex Bucket Diff
@cindex Bucket Truncation
@cindex Serialization
To save changes,
  the client posts only the bucket diff (@pxref{Bucket Diff}) to the
  Server (@pxref{Server}).
Because JSON serialization encodes @code{undefined} values as @code{null}
  (as noted in @ref{Bucket Diff}),
    and only the null in the tail position marks the truncation point,
    the Client first truncates the array to include only the first
      @code{null}.@footnote{
        The server would otherwise remove only the last index,
          even if multiple indexes were removed.}
An example is shown in @ref{f:client-diff}.

@float Figure, f:client-diff
@example
  // given (two unchanged, three removed)
  [ undefined, undefined, null, null, null ]

  // encodes into JSON as (bad; represents four unchanged, one removed)
  [ null, null, null, null, null ]

  // Client truncates to (two unchanged, >=2 removed)
  [ null, null, null ]
@end example
@caption{Client diff truncation}
@end float

This conversion is handled by
  @srcrefjs{client/transport,XhttpQuoteTransport}.
Examples can be found in the respective test case
  @testrefjs{client/transport,XhttpQuoteTransport}.