Secrets API

.github/workflows/framework-tests.yaml

@@ -37,7 +37,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.5", "3.6", "3.8", "3.10"]
+        python-version: ["3.8", "3.10"]
 
     steps:
       - uses: actions/checkout@v2
@@ -58,7 +58,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.5", "3.6", "3.8", "3.10"]
+        python-version: ["3.8", "3.10"]
 
     steps:
       - uses: actions/checkout@v2

ops/_private/timeconv.py

@@ -0,0 +1,55 @@
+# Copyright 2022 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Time conversion utilities."""
+
+import datetime
+import re
+
+# Matches yyyy-mm-ddTHH:MM:SS(.sss)ZZZ
+_TIMESTAMP_RE = re.compile(
+    r'(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?(.*)')
+
+# Matches [-+]HH:MM
+_TIMEOFFSET_RE = re.compile(r'([-+])(\d{2}):(\d{2})')
+
+
+def parse_rfc3339(s: str) -> datetime.datetime:
+    """Parse an RFC3339 timestamp.
+
+    This parses RFC3339 timestamps (which are a subset of ISO8601 timestamps)
+    that Go's encoding/json package produces for time.Time values.
+
+    Unfortunately we can't use datetime.fromisoformat(), as that does not
+    support more than 6 digits for the fractional second, nor the 'Z' for UTC.
+    """
+    match = _TIMESTAMP_RE.match(s)
+    if not match:
+        raise ValueError('invalid timestamp {!r}'.format(s))
+    y, m, d, hh, mm, ss, sfrac, zone = match.groups()
+
+    if zone in ('Z', 'z'):
+        tz = datetime.timezone.utc
+    else:
+        match = _TIMEOFFSET_RE.match(zone)
+        if not match:
+            raise ValueError('invalid timestamp {!r}'.format(s))
+        sign, zh, zm = match.groups()
+        tz_delta = datetime.timedelta(hours=int(zh), minutes=int(zm))
+        tz = datetime.timezone(tz_delta if sign == '+' else -tz_delta)
+
+    microsecond = round(float(sfrac or '0') * 1000000)
+
+    return datetime.datetime(int(y), int(m), int(d), int(hh), int(mm), int(ss),
+                             microsecond=microsecond, tzinfo=tz)

ops/charm.py

@@ -286,7 +286,7 @@ class ConfigChangedEvent(HookEvent):
       rescheduling, on unit upgrade/refresh, etc...
     - As a specific instance of the above point: when networking changes
       (if the machine reboots and comes up with a different IP).
-    - When the cloud admin reconfigures the charm via the juju CLI, i.e.
+    - When the cloud admin reconfigures the charm via the Juju CLI, i.e.
       `juju config my-charm foo=bar`. This event notifies the charm of
       its new configuration. (The event itself, however, is not aware of *what*
       specifically has changed in the config).
@@ -742,6 +742,143 @@ class PebbleReadyEvent(WorkloadEvent):
     """
 
 
+class SecretEvent(HookEvent):
+    """Base class for all secret events."""
+
+    def __init__(self, handle: 'Handle', id: str, label: Optional[str]):
+        super().__init__(handle)
+        self._id = id
+        self._label = label
+
+    @property
+    def secret(self) -> model.Secret:
+        """The secret instance this event refers to."""
+        backend = self.framework.model._backend
+        return model.Secret(backend=backend, id=self._id, label=self._label)
+
+    def snapshot(self) -> '_SerializedData':
+        """Used by the framework to serialize the event to disk.
+
+        Not meant to be called by charm code.
+        """
+        return {'id': self._id, 'label': self._label}
+
+    def restore(self, snapshot: '_SerializedData'):
+        """Used by the framework to deserialize the event from disk.
+
+        Not meant to be called by charm code.
+        """
+        self._id = cast(str, snapshot['id'])
+        self._label = cast(Optional[str], snapshot['label'])
+
+
+class SecretChangedEvent(SecretEvent):
+    """Event raised by Juju on the observer when the secret owner changes its contents.
+
+    When the owner of a secret changes the secret's contents, Juju will create
+    a new secret revision, and all applications or units that are tracking this
+    secret will be notified via this event that a new revision is available.
+
+    Typically, you will want to fetch the new content by calling
+    :meth:`ops.model.Secret.get_content` with :code:`refresh=True` to tell Juju to
+    start tracking the new revision.
+    """
+
+
+class SecretRotateEvent(SecretEvent):
+    """Event raised by Juju on the owner when the secret's rotation policy elapses.
+
+    This event is fired on the secret owner to inform it that the secret must
+    be rotated. The event will keep firing until the owner creates a new
+    revision by calling :meth:`ops.model.Secret.set_content`.
+    """
+
+    def defer(self):
+        """Secret rotation events are not deferrable (Juju handles re-invocation)."""
+        raise RuntimeError(
+            'Cannot defer secret rotation events. Juju will keep firing this '
+            'event until you create a new revision.')
+
+
+class SecretRemoveEvent(SecretEvent):
+    """Event raised by Juju on the owner when a secret revision can be removed.
+
+    When the owner of a secret creates a new revision, and after all
+    observers have updated to that new revision, this event will be fired to
+    inform the secret owner that the old revision can be removed.
+
+    Typically, you will want to call :meth:`ops.model.Secret.remove_revision` to
+    remove the now-unused revision.
+    """
+
+    def __init__(self, handle: 'Handle', id: str, label: Optional[str], revision: int):
+        super().__init__(handle, id, label)
+        self._revision = revision
+
+    @property
+    def revision(self) -> int:
+        """The secret revision this event refers to."""
+        return self._revision
+
+    def snapshot(self) -> '_SerializedData':
+        """Used by the framework to serialize the event to disk.
+
+        Not meant to be called by charm code.
+        """
+        data = super().snapshot()
+        data['revision'] = self._revision
+        return data
+
+    def restore(self, snapshot: '_SerializedData'):
+        """Used by the framework to deserialize the event from disk.
+
+        Not meant to be called by charm code.
+        """
+        super().restore(snapshot)
+        self._revision = cast(int, snapshot['revision'])
+
+
+class SecretExpiredEvent(SecretEvent):
+    """Event raised by Juju on the owner when a secret's expiration time elapses.
+
+    This event is fired on the secret owner to inform it that the secret revision
+    must be removed. The event will keep firing until the owner removes the
+    revision by calling :meth:`model.Secret.remove_revision()`.
+    """
+
+    def __init__(self, handle: 'Handle', id: str, label: Optional[str], revision: int):
+        super().__init__(handle, id, label)
+        self._revision = revision
+
+    @property
+    def revision(self) -> int:
+        """The secret revision this event refers to."""
+        return self._revision
+
+    def snapshot(self) -> '_SerializedData':
+        """Used by the framework to serialize the event to disk.
+
+        Not meant to be called by charm code.
+        """
+        data = super().snapshot()
+        data['revision'] = self._revision
+        return data
+
+    def restore(self, snapshot: '_SerializedData'):
+        """Used by the framework to deserialize the event from disk.
+
+        Not meant to be called by charm code.
+        """
+        super().restore(snapshot)
+        self._revision = cast(int, snapshot['revision'])
+
+    def defer(self):
+        """Secret expiration events are not deferrable (Juju handles re-invocation)."""
+        raise RuntimeError(
+            'Cannot defer secret expiration events. Juju will keep firing '
+            'this event until you create a new revision.')
+
+
 class CharmEvents(ObjectEvents):
     """Events generated by Juju pertaining to application lifecycle.
 
@@ -783,6 +920,11 @@ class CharmEvents(ObjectEvents):
     leader_settings_changed = EventSource(LeaderSettingsChangedEvent)
     collect_metrics = EventSource(CollectMetricsEvent)
 
+    secret_changed = EventSource(SecretChangedEvent)
+    secret_expired = EventSource(SecretExpiredEvent)
+    secret_rotate = EventSource(SecretRotateEvent)
+    secret_remove = EventSource(SecretRemoveEvent)
+
 
 class CharmBase(Object):
     """Base class that represents the charm overall.

ops/jujuversion.py

@@ -102,18 +102,23 @@ def from_environ(cls) -> 'JujuVersion':
         return cls(v)
 
     def has_app_data(self) -> bool:
-        """Determine whether this juju version knows about app data."""
+        """Determine whether this Juju version knows about app data."""
         return (self.major, self.minor, self.patch) >= (2, 7, 0)
 
     def is_dispatch_aware(self) -> bool:
-        """Determine whether this juju version knows about dispatch."""
+        """Determine whether this Juju version knows about dispatch."""
         return (self.major, self.minor, self.patch) >= (2, 8, 0)
 
     def has_controller_storage(self) -> bool:
-        """Determine whether this juju version supports controller-side storage."""
+        """Determine whether this Juju version supports controller-side storage."""
         return (self.major, self.minor, self.patch) >= (2, 8, 0)
 
     @property
     def has_secrets(self) -> bool:
         """Determine whether this Juju version supports the `secrets` feature."""
+        # Juju version 3.0.0 had an initial version of secrets, but:
+        # * In 3.0.2, secret-get "--update" was renamed to "--refresh", and
+        #   secret-get-info was separated into its own hook tool
+        # * In 3.0.3, a bug with observer labels was fixed (juju/juju#14916)
+        # TODO(benhoyt): update to 3.0.3+ once shipped (for juju/juju#14916 fix)
         return (self.major, self.minor, self.patch) >= (3, 0, 2)

ops/main.py

@@ -119,7 +119,7 @@ def _setup_event_links(charm_dir: Path, charm: 'CharmBase'):
     """
     # XXX: on windows this function does not accomplish what it wants to:
     #      it creates symlinks with no extension pointing to a .py
-    #      and juju only knows how to handle .exe, .bat, .cmd, and .ps1
+    #      and Juju only knows how to handle .exe, .bat, .cmd, and .ps1
     #      so it does its job, but does not accomplish anything as the
     #      hooks aren't 'callable'.
     link_to = os.path.realpath(os.environ.get("JUJU_DISPATCH_PATH", sys.argv[0]))
@@ -160,6 +160,14 @@ def _get_event_args(charm: 'CharmBase',
         workload_name = os.environ['JUJU_WORKLOAD_NAME']
         container = model.unit.get_container(workload_name)
         return [container], {}
+    elif issubclass(event_type, ops.charm.SecretEvent):
+        args: List[Any] = [
+            os.environ['JUJU_SECRET_ID'],
+            os.environ.get('JUJU_SECRET_LABEL'),
+        ]
+        if issubclass(event_type, (ops.charm.SecretRemoveEvent, ops.charm.SecretExpiredEvent)):
+            args.append(int(os.environ['JUJU_SECRET_REVISION']))
+        return args, {}
     elif issubclass(event_type, ops.charm.StorageEvent):
         storage_id = os.environ.get("JUJU_STORAGE_ID", "")
         if storage_id:
@@ -399,7 +407,7 @@ def main(charm_class: Type[ops.charm.CharmBase],
     if use_juju_for_storage:
         if dispatcher.is_restricted_context():
             # TODO: jam 2020-06-30 This unconditionally avoids running a collect metrics event
-            #  Though we eventually expect that juju will run collect-metrics in a
+            #  Though we eventually expect that Juju will run collect-metrics in a
             #  non-restricted context. Once we can determine that we are running collect-metrics
             #  in a non-restricted context, we should fire the event as normal.
             logger.debug('"%s" is not supported when using Juju for storage\n'