Extensions via entry points

- auto-loading of modules in the 'docker_registry.extensions' entry
  point group
- preliminary documentation
- define and encourage API on top of signals and config

Author: Andy Goldstein

docker_registry/extensions/README.md

@@ -0,0 +1,112 @@
+# docker-registry extensions
+
+You can further extend the registry behavior by authoring specially crafted Python packages and listening to signals.
+
+## For users
+
+### Word of caution
+
+Installing and running third-party addons usually grant execution privileges and access to sensitive information.
+docker-registry extensions are no different, and you need to use caution and to fully understand that said addons once run likely have unlimited access to your configuration, including secrets, certificates, etcetera.
+
+Please give this a think before you run random packages.
+
+### Using an extension
+
+1. Find the extension you are interested in. Usually, a docker container packing that extension is available.
+2. Review this extension's configuration settings, edit your configuration file accordingly, and run your registry.
+
+
+## For developers
+
+
+### Scaffolding
+
+1. Start a new package (named `foo`)
+2. Create whatever module folders you wish (make sure you have an empty `__init__.py` in each folder)
+3. Create a setup.py for your package (and then call `python setup.py develop`):
+
+```
+setuptools.setup(
+    entry_points = {
+        'docker_registry.extensions': [
+            '[some name] = [your.module]'
+        ]
+    },
+```
+
+`[some name]` is currently ignored but it is a required value.
+
+`[your.module]` is the name of your extension module. It will be imported when the entry point is loaded.
+
+4. Run your registry with DEBUG=true so that gunicorn reloads on file change
+
+### Installing
+
+As soon as your python package is installed on the system, your code will get executed.
+The main communication API with the registry is through signals (see below).
+
+As far as your users are concerned, all they have to do should be `pip install my-foo-package` (you may require them to add some specific configuration, including to explicitly enable your extension - see below).
+
+That's it.
+
+
+### API
+
+This very simple example will print when a tag is created:
+
+```
+from docker_registry.lib import signals
+
+
+def receiver():
+    print('I am a tag creation receiver')
+
+signals.tag_created.connect(receiver)
+
+```
+
+You can access configuration options through the config API:
+
+```
+from docker_registry.lib import config
+
+myconfig = config.load()
+```
+
+That will give you the full configuration. We recommend that you place extension configuration settings in the `extensions` portion of the configuration file, e.g.:
+
+```
+extensions:
+    my_cool_extension:
+        some_key: some_value
+```
+
+And you would then reference your configuration options like so:
+
+```
+myconfig.extensions.my_cool_extension.some_key
+```
+
+For convenience, you may also use the following APIs from core:
+
+```
+from docker_registry.core import compat
+from docker_registry.core import exceptions
+```
+
+(see the code...)
+
+### Versioning and compatibility
+
+Right now there is no versioning strategy (save on core), although we will do our best not to break the API for `signals` and `config`.
+
+Any other docker-registry API should be considered private / unstable, and as a responsible extension author, you should think twice before using said internals...
+
+### Packaging for distribution
+
+The preferred way to package is through pypi.
+
+Your package must depend on `docker-registry-core>=2,<3`
+
+You are strongly encouraged to also provide docker containers for your extension (base it on `FROM registry:latest`), and to give the registry maintainers a ping.

docker_registry/extensions/__init__.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+import pkg_resources
+
+
+def boot():
+    for ep in pkg_resources.iter_entry_points('docker_registry.extensions'):
+        ep.load()
+
+
+def list():
+    return list(pkg_resources.iter_entry_points('docker_registry.extensions'))

docker_registry/extensions/factory.py

@@ -17,17 +17,19 @@ class Config(object):
      * interpolate from ENV
     """
 
-    def __init__(self, config=''):
-        try:
+    def __init__(self, config=None):
+        if config is None:
+            config = {}
+        if isinstance(config, compat.basestring):
+            try:
+                self._config = yaml.load(config)
+            except Exception as e:
+                # Failed yaml loading? Stop here!
+                raise exceptions.ConfigError(
+                    'Config is not valid yaml (%s): \n%s' % (e, config))
+        else:
             # Config is kept as-is...
             self._config = config
-            # ... save Strings, that are yaml loaded
-            if isinstance(config, compat.basestring):
-                self._config = yaml.load(config)
-        except Exception as e:
-            # Failed yaml loading? Stop here!
-            raise exceptions.ConfigError(
-                'Config is not valid yaml (%s): \n%s' % (e, config))
 
     def __repr__(self):
         return repr(self._config)
@@ -77,14 +79,7 @@ def __contains__(self, key):
         return key in self._config
 
 
-_config = None
-
-
-def load():
-    global _config
-    if _config is not None:
-        return _config
-
+def _init():
     flavor = os.environ.get('SETTINGS_FLAVOR', 'dev')
     config_path = os.environ.get('DOCKER_REGISTRY_CONFIG', 'config.yml')
 
@@ -97,25 +92,36 @@ def load():
         raise exceptions.FileNotFoundError(
             'Heads-up! File is missing: %s' % config_path)
 
-    _config = Config(f.read())
+    conf = Config(f.read())
     if flavor:
-        _config = _config[flavor]
-        _config.flavor = flavor
+        conf = conf[flavor]
+        conf.flavor = flavor
 
-    if _config.privileged_key:
+    if conf.privileged_key:
         try:
-            f = open(_config.privileged_key)
+            f = open(conf.privileged_key)
         except Exception:
             raise exceptions.FileNotFoundError(
-                'Heads-up! File is missing: %s' % _config.privileged_key)
+                'Heads-up! File is missing: %s' % conf.privileged_key)
 
         try:
-            _config.privileged_key = rsa.PublicKey.load_pkcs1(f.read())
+            conf.privileged_key = rsa.PublicKey.load_pkcs1(f.read())
         except Exception:
             raise exceptions.ConfigError(
-                'Key at %s is not a valid RSA key' % _config.privileged_key)
+                'Key at %s is not a valid RSA key' % conf.privileged_key)
+
+    if conf.index_endpoint:
+        conf.index_endpoint = conf.index_endpoint.strip('/')
+
+    return conf
+
+_config = None
+
+
+def load():
+    global _config
 
-    if _config.index_endpoint:
-        _config.index_endpoint = _config.index_endpoint.strip('/')
+    if not _config:
+        _config = _init()
 
     return _config

docker_registry/lib/config.py

@@ -15,6 +15,8 @@
     except Exception as e:
         raise(Exception('Failed to init new relic agent %s' % e))
 
+from .extensions import factory
+factory.boot()
 from .run import app
 
 if __name__ == '__main__':

docker_registry/wsgi.py

@@ -50,7 +50,8 @@
             'docker_registry.server',
             'docker_registry.lib',
             'docker_registry.storage',
-            'docker_registry.lib.index']
+            'docker_registry.lib.index',
+            'docker_registry.extensions']
 
 namespaces = ['docker_registry', 'docker_registry.drivers']
 

setup.py

@@ -32,9 +32,14 @@ def setUp(self):
 
         self.c = config.Config(open(p, 'rb').read())
 
-    def test__init__(self):
+    def test__init__parse_error(self):
         self.assertRaises(config.exceptions.ConfigError, config.Config, '\1')
 
+    def test__init__no_arg(self):
+        self.c = config.Config()
+        assert self.c['whatevertheflush'] is None
+        assert self.c.whatevertheflush is None
+
     @mock.patch('__builtin__.repr')
     def test__repr(self, r):
         self.c.__repr__()