Merge ~kwmonroe/layer-snap:feature/snapd-refresh into ~stub/layer-snap:master

[Kevin W Monroe]

Support a new 'snapd_refresh' config option, which sets the snapd refresh.timer option.

[Stuart Bishop (stub)]

This all looks good.

review: Approve

diff --git a/README.md b/README.md
index 254649a..1ba2ebe 100644
--- a/README.md
+++ b/README.md
@@ -86,13 +86,52 @@ have been installed, so you do not need to worry about installation
 order.
 
 
+### Snap Refresh
+
+By default, the `snapd` daemon will query the Snap Store four (4)
+times per day to process updates for installed snaps. This layer provides
+a charm configuration option for authors and operators to control this
+refresh frequency.
+
+>NOTE: this is a global configuration option and will affect the refresh
+time for all snaps installed on a system.
+
+>NOTE: requires snapd 2.31 or higher.
+
+Examples:
+
+```sh
+## refresh snaps every tuesday
+juju config telegraf snapd_refresh="tue"
+
+## refresh snaps at 11pm on the last (5th) friday of the month
+juju config telegraf snapd_refresh="fri5,23:00"
+
+## use the system default refresh timer
+juju config telegraf snapd_refresh=""
+```
+
+Currently, the `snapd` refresh timer may be delayed up to one (1) month. This
+can be configured using the `max` option:
+
+```sh
+## delay snap refreshes as long as possible
+juju config telegraf snapd_refresh="max"
+```
+
+For more information on the possible values for `snapd_refresh`, see the
+*refresh.timer* section in the [system options][] documentation.
+
+[system options]: https://forum.snapcraft.io/t/system-options/87
+
+
 ## Usage
 
 If you have defined your snaps in layer.yaml for automatic installation
 and updates, there is nothing further to do.
 
 ### API
- 
+
 If your charm need to control installation, update and removal of snaps
 itself, the following methods are available via the `charms.layer.snap`
 package::
diff --git a/config.yaml b/config.yaml
index 754d46a..939cf3d 100644
--- a/config.yaml
+++ b/config.yaml
@@ -25,3 +25,12 @@ options:
     description: |
       The address of a Snappy Enterprise Proxy to use for snaps
       e.g. http://snap-proxy.example.com
+  snapd_refresh:
+    default: ""
+    type: string
+    description: |
+      How often snapd handles updates for installed snaps. The default
+      (an empty string) is 4x per day. Set to "max" to check once per month
+      based on the charm deployment date. You may also set a custom string as
+      described in the 'refresh.timer' section here:
+        https://forum.snapcraft.io/t/system-options/87
diff --git a/lib/charms/layer/snap.py b/lib/charms/layer/snap.py
index 80e94e4..be32056 100644
--- a/lib/charms/layer/snap.py
+++ b/lib/charms/layer/snap.py
@@ -22,6 +22,7 @@ from charms import layer
 from charms import reactive
 from charms.reactive.helpers import any_file_changed, data_changed
 from time import sleep
+from datetime import datetime, timedelta
 
 
 def install(snapname, **kw):
@@ -178,6 +179,41 @@ def set(snapname, key, value):
         ['snap', 'set', snapname, '{}={}'.format(key, value)])
 
 
+def set_refresh_timer(timer=''):
+    '''Set the system refresh.timer option (snapd 2.31+)
+
+    This method sets how often snapd will refresh installed snaps. Call with
+    an empty timer string to use the system default (currently 4x per day).
+    Use 'max' to schedule refreshes as far into the future as possible
+    (currently 1 month). Also accepts custom timer strings as defined in the
+    refresh.timer section here:
+      https://forum.snapcraft.io/t/system-options/87
+
+    This method does not validate custom strings and will lead to a
+    CalledProcessError if an invalid string is given.
+
+    :param: timer: empty string (default), 'max', or custom string
+    '''
+    if timer == 'max':
+        # A month from yesterday is the farthest we should delay to safely stay
+        # under the 1 month max. Translate that to a valid refresh.timer value.
+        # Examples:
+        # - Today is Friday the 13th, set the refresh timer to
+        # 'thu2' (Thursday the 12th is the 2nd thursday of the month).
+        # - Today is Tuesday the 1st, set the refresh timer to
+        # 'mon5' (Monday the [28..31] is the 5th monday of the month).
+        yesterday = datetime.now() - timedelta(1)
+        dow = yesterday.strftime('%a').lower()
+        # increment after int division because we want occurrence 1-5, not 0-4.
+        occurrence = yesterday.day // 7 + 1
+        timer = '{}{}'.format(dow, occurrence)
+
+    # NB: 'system' became synonymous with 'core' in 2.32.5, but we use 'core'
+    # here to ensure max compatibility.
+    set(snapname='core', key='refresh.timer', value=timer)
+    subprocess.check_call(['systemctl', 'restart', 'snapd.service'])
+
+
 def get(snapname, key):
     '''Gets configuration options for a snap
 
diff --git a/reactive/snap.py b/reactive/snap.py
index 884dc63..d646527 100644
--- a/reactive/snap.py
+++ b/reactive/snap.py
@@ -31,6 +31,7 @@ from charmhelpers.core.host import write_file
 from charms import layer
 from charms import reactive
 from charms.layer import snap
+from charms.reactive import when
 from charms.reactive.helpers import data_changed
 
 
@@ -263,6 +264,14 @@ def configure_snap_enterprise_proxy():
             'Proxy ID from header did not match store assertion: ' + e.output)
 
 
+@when('config.changed.snapd_refresh')
+def change_snapd_refresh():
+    """Set the system refresh.timer option"""
+    ensure_snapd_min_version('2.31')
+    timer = hookenv.config()['snapd_refresh']
+    snap.set_refresh_timer(timer)
+
+
 # Per https://github.com/juju-solutions/charms.reactive/issues/33,
 # this module may be imported multiple times so ensure the
 # initialization hook is only registered once. I have to piggy back