Mike Gerwitz

Activist for User Freedom

path: root/doc
diff options
authorMike Gerwitz <gerwitzm@lovullo.com>2017-06-28 16:12:08 -0400
committerMike Gerwitz <gerwitzm@lovullo.com>2017-06-28 16:33:24 -0400
commit0c24e3d2807a3d5aa5f9c768f449c6ba2b7fc6dd (patch)
treedf1e9404787e07f64b9690dd79e60933fe35cb32 /doc
parent65ab92f7019bbe469345ceeed9a771350c1088f2 (diff)
Populate document metadata using Data APIs
What a cluster. This was a lot of work to work around existing, bad APIs; there is no time to refactor at the moment; this already took much longer than expected.
Diffstat (limited to 'doc')
3 files changed, 104 insertions, 3 deletions
diff --git a/doc/macros.texi b/doc/macros.texi
index 7340491..e5a283c 100644
--- a/doc/macros.texi
+++ b/doc/macros.texi
@@ -203,6 +203,10 @@ Program@tie{}XML
@end macro
+@macro dapiref
+@dapi (@pxref{Data API,,Data@tie{}API})
+@end macro
@c todo: link to reference directly
@macro proguicref{ref}
`\ref\' @proguicrefsuffix
diff --git a/doc/program.texi b/doc/program.texi
index 76d6482..94a1e12 100644
--- a/doc/program.texi
+++ b/doc/program.texi
@@ -40,8 +40,11 @@ Programs are ideally compiled from a @ref{Program XML,,Program@tie{}XML}
* Program UI::
* Program XML::
+* Document Metadata:: Document-level data that cannot be modified by
+ the client.
@end menu
@node Program UI
@section Program UI
@@ -220,3 +223,60 @@ Within the context of the @progxml,
It reads as a sentence:
``@samp{vacant_desc}'' is applicable when we should @tie{}``describe
a vacant property''.
+@node Document Metadata
+@section Document Metadata
+@dfn{Document metadata} are metadata that describe certain aspects of the document;
+ they are stored adjacent to the bucket in @samp{meta}@tie{}on the
+ document root.@footnote{
+ Terminology note: ``document'' and ``quote'' are the same thing;
+ the latter is transitioning to the former for generality.}
+They should be used in place of a bucket field any time
+ the client has no business knowing about the data.
+The @samp{meta} record is called the @dfn{Metabucket}.
+@c don't use a dapi xref here; don't want to confuse the reader by
+@c directing them away from this section before they continue reading
+@tip{Metadata in the Metabucket should@tie{}@emph{not} be
+ directly populated by external systems@mdash{
+ }@dapi integration should be used instead (see below).}
+Metadata can be populated using any@tie{}@dapiref@mdash{
+ }return data populate the Metabucket in the same way that they
+ populate the Bucket.
+Definitions are stored in @code{meta.fields},
+ as shown in @ref{f:meta-fields}.
+@float Figure, f:meta-fields
+ ["string(name)": @{
+ "desc": "string",
+ "dapi": @{
+ "name": "string",
+ "map": @{
+ "string(dest field)": "string(source field)"
+ @}
+ @}
+ @}
+@end example
+@caption{Format of @code{meta.fields}.}
+@end float
+Further, a key-value mapping of all bucket fields that@mdash{
+ }when modified,
+ need to result in a metadata API@tie{}call@mdash{
+ }are stored in the @code{mapis}@tie{}object;
+ this is shown in @ref{f:mapis}.
+@float Figure, f:mapis
+ ["string(field name)"]: [ "string(dapi name)", ... ]
+@end example
+@caption{Format of @code{mapis}.}
+@end float
diff --git a/doc/server.texi b/doc/server.texi
index 752f74a..ca9d777 100644
--- a/doc/server.texi
+++ b/doc/server.texi
@@ -56,9 +56,10 @@ The HTTP server is managed by
-* Requests:: Handling HTTP requests
-* Posting Data:: Handling step saves and other posts.
-* Encryption Service:: Managing sensitive data.
+* Requests:: Handling HTTP requests.
+* Posting Data:: Handling step saves and other posts.
+* Server-Side Data API Calls:: Accessing external resources on the server.
+* Encryption Service:: Managing sensitive data.
@end menu
@@ -203,6 +204,11 @@ Once those basic checks have passed,
already been discarded by the first step in this list);
+ Server-side @dapi{} calls (@pxref{Data API}) are triggered using the
+ diff as input data and an empty bucket for response storage
+ (@pxref{Server-Side Data API Calls});
+ @item
@cindex Premium calculation date
The last premium calculation date is cleared (indicating that
premiums are no longer valid);@footnote{
@@ -226,6 +232,37 @@ Once those basic checks have passed,
+@node Server-Side Data API Calls
+@section Server-Side Data API Calls
+@maintenance{This makes use of @srcrefjs{server/meta,DapiMetaSource}
+ to encapsulate the horrible API of @srcrefjs{dapi,DataApiManager};
+ the latter needs cleanup to remove the former.}
+@cindex Data API
+@cindex Document metadata
+Server-side @dapi{} calls (@pxref{Data API}) are triggered on
+ step save (@pxref{Posting Data}) and are handled much like they are
+ on the client.
+Such calls are made automatically only for document metadata.
+Results of sever-side calls are @emph{not} written to the bucket
+ and are therefore useful for data that the client should not be
+ permitted to modify;
+ it also allows data to be kept secret from the client.@footnote{
+ All bucket data is served to the client,
+ with the exception of internal fields if the user is non-internal.}
+@dapi{} results on the client can be mapped back to multiple bucket values;
+ the server, however, has serious concerns with how data are
+ propagated for data integrity and security reasons.
+ document metadata can be structured,
+ unlike the Bucket which has a rigid matrix format (@pxref{Bucket}).
+ the entire response is mapped into the parent field;
+ defined return values are used only for filtering.
@node Encryption Service
@section Encryption Service