lib/repo: Add OSTREE_REPO_METADATA_REF as a well-known metadata store

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

diff --git a/apidoc/ostree-experimental-sections.txt b/apidoc/ostree-experimental-sections.txt
index 4c71fad248a5304d7b89f0de0f519a161b288085..a2c2c29549571a6e672ae8a652c0d34fbe7d817a 100644 (file)
--- 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 ea7a778961f72404e54c2fbab3f8fad1ff33f20b..f1e964b7bc29fac2c8221b5315743f3897de871c 100644 (file)
--- 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