schema: Add known_fingerprints option to schema command

When client requests schema it can list fingerprints of cached schemas
and server responds with SchemaUpToDate exception specifying fingeprint
of schema to use.

https://fedorahosted.org/freeipa/ticket/4739

Reviewed-By: Jan Cholasta <jcholast@redhat.com>

API.txt

@@ -3974,7 +3974,8 @@ output: Entry('result')
 output: Output('summary', type=[<type 'unicode'>, <type 'NoneType'>])
 output: PrimaryKey('value')
 command: schema
-args: 0,1,1
+args: 0,2,1
+option: Str('known_fingerprints*')
 option: Str('version?')
 output: Output('result')
 command: selfservice_add

VERSION

@@ -90,5 +90,5 @@ IPA_DATA_VERSION=20100614120000
 #                                                      #
 ########################################################
 IPA_API_VERSION_MAJOR=2
-IPA_API_VERSION_MINOR=198
-# Last change: dns: fix dns_update_system_records to work with thin client
+IPA_API_VERSION_MINOR=199
+# Last change: schema: Add known_fingerprints option to schema command

ipalib/errors.py

@@ -1820,6 +1820,24 @@ class CertificateInvalidError(CertificateError):
     format = _('%(name)s certificate is not valid')
 
 
+class SchemaUpToDate(ExecutionError):
+    """
+    **4311** Raised by server when client asks for metadata but
+    already has current version. Exception's attribute 'fingerprint'
+    identitfies schema version to use. Attribute 'ttl' specifies how
+    long (in seconds) before client should check for schema update.
+
+    For example:
+    >>> raise SchemaUpToDate(fingerprint=u'deadbeef', ttl=3600)
+    Traceback (most recent call last):
+      ...
+    SchemaUpToDate: Schema is up to date (FP 'deadbeef', TTL 3600 s)
+    """
+
+    errno = 4311
+    format = _("Schema is up to date (FP '%(fingerprint)s', TTL %(ttl)s s)")
+
+
 class DNSError(ExecutionError):
     """
     **4400** Base class for DNS execution errors (*4400 - 4499*).

ipaserver/plugins/schema.py

@@ -695,6 +695,13 @@ class output_find(BaseParamSearch):
 class schema(Command):
     NO_CLI = True
 
+    takes_options = (
+        Str(
+            'known_fingerprints*',
+            label=_("Fingerprint of schema cached by client")
+        ),
+    )
+
     @staticmethod
     def _calculate_fingerprint(data):
         """
@@ -748,4 +755,10 @@ class schema(Command):
         schema['fingerprint'] = schema_fp
         schema['ttl'] = SCHEMA_TTL
 
+        if schema['fingerprint'] in kwargs.get('known_fingerprints', []):
+            raise errors.SchemaUpToDate(
+                fingerprint=schema['fingerprint'],
+                ttl=schema['ttl'],
+            )
+
         return dict(result=schema)

pylint_plugins.py

@@ -125,6 +125,10 @@ ipa_class_members = {
     'ipalib.errors.ValidationError': [
         'error',
     ],
+    'ipalib.errors.SchemaUpToDate': [
+        'fingerprint',
+        'ttl',
+    ],
     'ipalib.messages.PublicMessage': [
         'msg',
         'strerror',