From acb14648d7fee86932038a815f11e307e3e13052 Mon Sep 17 00:00:00 2001
From: Philip Withnall <withnall@endlessm.com>
Date: Tue, 11 Jul 2017 20:46:03 +0100
Subject: [PATCH] lib/repo: Add OSTREE_REPO_METADATA_REF as a well-known
 metadata store
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

As discussed in https://github.com/ostreedev/ostree/pull/946, the
summary file is becoming an unsigned cache of ref information; any
additional metadata for the repository needs to move elsewhere in order
to remain signed. Introduce OSTREE_REPO_METADATA_REF as the well-known
name of a ref where such metadata can live, as the metadata on
contentless commits.

Don’t yet update the documentation for summary-related methods to
mention this, since it’s still hidden behind the
--enable-experimental-api configure option.

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

Closes: #946
Approved by: cgwalters
---
 apidoc/ostree-experimental-sections.txt |  1 +
 src/libostree/ostree-repo.h             | 26 +++++++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/apidoc/ostree-experimental-sections.txt b/apidoc/ostree-experimental-sections.txt
index 4c71fad2..a2c2c295 100644
--- a/apidoc/ostree-experimental-sections.txt
+++ b/apidoc/ostree-experimental-sections.txt
@@ -28,6 +28,7 @@ ostree_repo_find_remotes_finish
 ostree_repo_pull_from_remotes_async
 ostree_repo_pull_from_remotes_finish
 ostree_repo_resolve_keyring_for_collection
+OSTREE_REPO_METADATA_REF
 </SECTION>
 
 <SECTION>
diff --git a/src/libostree/ostree-repo.h b/src/libostree/ostree-repo.h
index ea7a7789..f1e964b7 100644
--- a/src/libostree/ostree-repo.h
+++ b/src/libostree/ostree-repo.h
@@ -1244,6 +1244,32 @@ gboolean ostree_repo_regenerate_summary (OstreeRepo     *self,
                                          GCancellable   *cancellable,
                                          GError        **error);
 
+#ifdef OSTREE_ENABLE_EXPERIMENTAL_API
+
+/**
+ * OSTREE_REPO_METADATA_REF:
+ *
+ * The name of a ref which is used to store metadata for the entire repository,
+ * such as its expected update time (`ostree.summary.expires`), name, or new
+ * GPG keys. Metadata is stored on contentless commits in the ref, and hence is
+ * signed with the commits.
+ *
+ * This supersedes the additional metadata dictionary in the `summary` file
+ * (see ostree_repo_regenerate_summary()), as the use of a ref means that the
+ * metadata for multiple upstream repositories can be included in a single mirror
+ * repository, disambiguating the refs using collection IDs. In order to support
+ * peer to peer redistribution of repository metadata, repositories must set a
+ * collection ID (ostree_repo_set_collection_id()).
+ *
+ * Users of OSTree may place arbitrary metadata in commits on this ref, but the
+ * keys must be namespaced by product or developer. For example,
+ * `exampleos.end-of-life`. The `ostree.` prefix is reserved.
+ *
+ * Since: 2017.8
+ */
+#define OSTREE_REPO_METADATA_REF "ostree-metadata"
+
+#endif  /* OSTREE_ENABLE_EXPERIMENTAL_API */
 
 G_END_DECLS