Add support for using relation ids to refer unambiguously to relations.

source/drafts/relation-reference.rst

+Relation references
+-------------------

[niemeyer, 2012/03/20 13:31:22]

Please check the other specs to see how they format headers and use the same
syntax. I believe it's === for the first header and --- for the internal ones.

[jimbaker, 2012/03/22 04:17:53]

Done.

+
+A service may **provide** an interface to multiple consuming services
+with the same relation name; each of these is a different established
+relation. For example, the ``mysql5`` service might provide the
+``mysql`` interface to multiple consuming clients using the relation
+name ``db``. When interacting with a given consuming client, relation
+hooks executing on ``mysql5`` service units in turn would be named
+``db-relation-joined``, ``db-relation-changed``, and
+``db-relation-departed``. In addition, the environment variable
+`$JUJU_RELATION` would be set to ``db``.
+
+This scenario implies that there is potential ambiguity in using the
+relation name to refer to the specific relation between a provider and
+a consumer. However, this ambiguity is currently rarely seen. This is
+because relation hooks are always executed in the context of a
+specific relation, as well as any settings on this relation. This
+locality avoids most ambiguity in actual usage.
+
+But ambiguity can arise in the following scenarios:
+
+  * Relation hooks are used to change local state, so it is currently
+    possible for the ambiguity in referring to a relation to become
+    visible over cumulative hook executions. Using appropriate
+    relation settings can be used to distinguish the consumer, so
+    there is a workaround.
+
+  * To enable the new feature of using relation hook commands to
+    work with other relations, or for these hook commands to be used
+    in nonrelation hooks, it is essential to have a nonambiguous
+    reference.
+
+Therefore, to completely specify a relation, it is necessary to use
+its relation id, not the relation name. However, the use of relation

[niemeyer, 2012/03/20 13:31:22]

Remove content after the dot. We'll use it later.

[jimbaker, 2012/03/22 04:17:53]

Done.

[niemeyer, 2012/03/22 18:20:40]

Not done.

+ids is restricted: relation ids are only visible inside relation hooks
+and/or relation hook commands. In particular, they are never seen in
+`juju status` output.
+
+To ensure readibility of the relation id, its format is specified to
+be::
+
+  <relation name>:<normalized internal relation id>
+
+Normalization removes any padding zeros from the internal id.  In
+addition, a new environment variable, `$JUJU_RELATION_ID`, will always

[niemeyer, 2012/03/20 13:31:22]

In addition to normalization we're setting an environment variable? That's a
different topic. Break line, and bring back the earlier text merged with it:

"""
Right now relation ids are only visible inside relation hooks, via the
$JUJU_RELATION_ID environment variable. In particular, they are not visible in
the output of "juju status".
"""

[jimbaker, 2012/03/22 04:17:53]

Done.

[niemeyer, 2012/03/22 18:20:40]

Not done.

+be set to the relation id in the context of relation hooks.
+
+For example, if the relation is associated with relation name ``db`` and
+the specific interal relation id is ``relation-0000000042``, then the
+relation id is ``db:42``. The relation hooks ``db-relation-joined``,
+etc., will have `$JUJU_RELATION_ID` set to ``db:42``. In addition,
+this format further implies that relation id is not globally
+unique. If the provider uses the relation name ``db`` and a consumer
+uses the relation name ``database``, then for interal relation id
+``relation-0000000042``, ``db:42`` and ``database:42`` could both be
+in use. However, it is not intended that relation ids be shared, or
+even publicly visible to an admin, so this should not pose an issue.
+
+
+References
+~~~~~~~~~~

[niemeyer, 2012/03/20 13:31:22]

I believe we use --- for internal headers.

[jimbaker, 2012/03/22 04:17:53]

Done.

+
+Motivation for relation ids is mentioned in `bug #767195:
+https://bugs.launchpad.net/juju/+bug/767195`_: Hooks must be able to
+enumerate and query relations. In addition, possible formats are
+discussed.