libostree: Add some additional metadata to the summary file

• Commit timestamps, so it’s easy to work out whether a given commit is
   newer than the one we have locally
 • Summary file timestamp, so it’s easy to work out whether the summary
   file is more up to date than another summary file
 • Summary file expiry time, so clients can work out when they should
   expect the summary file to next be updated, and hence can query for
   it at roughly the right time

The expiry time requires input from the user, so is currently never set
automatically. Programs using libostree can set it if they wish.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

Closes: #826
Approved by: cgwalters

src/libostree/ostree-core.h

@@ -158,6 +158,17 @@ typedef enum {
  * - a(s(taya{sv})) - Map of ref name -> (latest commit size, latest commit checksum, additional metadata), sorted by ref name
  * - a{sv} - Additional metadata, at the current time the following are defined:
  *   - key: "ostree.static-deltas", value: a{sv}, static delta name -> 32 bytes of checksum
+ *   - key: "ostree.summary.last-modified", value: t, timestamp (seconds since
+ *     the Unix epoch in UTC, big-endian) when the summary was last regenerated
+ *     (similar to the HTTP `Last-Modified` header)
+ *   - key: "ostree.summary.expires", value: t, timestamp (seconds since the
+ *     Unix epoch in UTC, big-endian) after which the summary is considered
+ *     stale and should be re-downloaded if possible (similar to the HTTP
+ *     `Expires` header)
+ *
+ * The currently defined keys for the `a{sv}` of additional metadata for each commit are:
+ *  - key: `ostree.commit.timestamp`, value: `t`, timestamp (seconds since the
+ *    Unix epoch in UTC, big-endian) when the commit was committed
  */
 #define OSTREE_SUMMARY_GVARIANT_STRING "(a(s(taya{sv}))a{sv})"
 #define OSTREE_SUMMARY_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_SUMMARY_GVARIANT_STRING)