mediagoblin/plugins/api/tools.py

   1 # GNU MediaGoblin -- federated, autonomous media hosting
   2 # Copyright (C) 2011, 2012 MediaGoblin contributors.  See AUTHORS.
   3 #
   4 # This program is free software: you can redistribute it and/or modify
   5 # it under the terms of the GNU Affero General Public License as published by
   6 # the Free Software Foundation, either version 3 of the License, or
   7 # (at your option) any later version.
   8 #
   9 # This program is distributed in the hope that it will be useful,
  10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 # GNU Affero General Public License for more details.
  13 #
  14 # You should have received a copy of the GNU Affero General Public License
  15 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 import logging
  18 import json
  19
  20 from functools import wraps
  21 from urlparse import urljoin
  22 from werkzeug.exceptions import Forbidden
  23 from werkzeug.wrappers import Response
  24 from mediagoblin import mg_globals
  25 from mediagoblin.tools.pluginapi import PluginManager
  26 from mediagoblin.storage.filestorage import BasicFileStorage
  27
  28 _log = logging.getLogger(__name__)
  29
  30
  31 class Auth(object):
  32     '''
  33     An object with two significant methods, 'trigger' and 'run'.
  34
  35     Using a similar object to this, plugins can register specific
  36     authentication logic, for example the GET param 'access_token' for OAuth.
  37
  38     - trigger: Analyze the 'request' argument, return True if you think you
  39       can handle the request, otherwise return False
  40     - run: The authentication logic, set the request.user object to the user
  41       you intend to authenticate and return True, otherwise return False.
  42
  43     If run() returns False, an HTTP 403 Forbidden error will be shown.
  44
  45     You may also display custom errors, just raise them within the run()
  46     method.
  47     '''
  48     def trigger(self, request):
  49         raise NotImplemented()
  50
  51     def __call__(self, request, *args, **kw):
  52         raise NotImplemented()
  53
  54
  55 def json_response(serializable, _disable_cors=False, *args, **kw):
  56     '''
  57     Serializes a json objects and returns a werkzeug Response object with the
  58     serialized value as the response body and Content-Type: application/json.
  59
  60     :param serializable: A json-serializable object
  61
  62     Any extra arguments and keyword arguments are passed to the
  63     Response.__init__ method.
  64     '''
  65     response = Response(json.dumps(serializable), *args, content_type='application/json', **kw)
  66
  67     if not _disable_cors:
  68         cors_headers = {
  69                 'Access-Control-Allow-Origin': '*',
  70                 'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
  71                 'Access-Control-Allow-Headers': 'Content-Type, X-Requested-With'}
  72         for key, value in cors_headers.iteritems():
  73             response.headers.set(key, value)
  74
  75     return response
  76
  77
  78 def get_entry_serializable(entry, urlgen):
  79     '''
  80     Returns a serializable dict() of a MediaEntry instance.
  81
  82     :param entry: A MediaEntry instance
  83     :param urlgen: An urlgen instance, can be found on the request object passed
  84     to views.
  85     '''
  86     return {
  87             'user': entry.get_uploader.username,
  88             'user_id': entry.get_uploader.id,
  89             'user_bio': entry.get_uploader.bio,
  90             'user_bio_html': entry.get_uploader.bio_html,
  91             'user_permalink': urlgen('mediagoblin.user_pages.user_home',
  92                 user=entry.get_uploader.username,
  93                 qualified=True),
  94             'id': entry.id,
  95             'created': entry.created.isoformat(),
  96             'title': entry.title,
  97             'license': entry.license,
  98             'description': entry.description,
  99             'description_html': entry.description_html,
 100             'media_type': entry.media_type,
 101             'state': entry.state,
 102             'permalink': entry.url_for_self(urlgen, qualified=True),
 103             'media_files': get_media_file_paths(entry.media_files, urlgen)}
 104
 105
 106 def get_media_file_paths(media_files, urlgen):
 107     '''
 108     Returns a dictionary of media files with `file_handle` => `qualified URL`
 109
 110     :param media_files: dict-like object consisting of `file_handle => `listy
 111     filepath` pairs.
 112     :param urlgen: An urlgen object, usually found on request.urlgen.
 113     '''
 114     media_urls = {}
 115
 116     for key, val in media_files.items():
 117         if isinstance(mg_globals.public_store, BasicFileStorage):
 118             # BasicFileStorage does not provide a qualified URI
 119             media_urls[key] = urljoin(
 120                     urlgen('index', qualified=True),
 121                     mg_globals.public_store.file_url(val))
 122         else:
 123             media_urls[key] = mg_globals.public_store.file_url(val)
 124
 125     return media_urls
 126
 127
 128 def api_auth(controller):
 129     '''
 130     Decorator, allows plugins to register auth methods that will then be
 131     evaluated against the request, finally a worthy authenticator object is
 132     chosen and used to decide whether to grant or deny access.
 133     '''
 134     @wraps(controller)
 135     def wrapper(request, *args, **kw):
 136         auth_candidates = []
 137
 138         for auth in PluginManager().get_hook_callables('auth'):
 139             if auth.trigger(request):
 140                 _log.debug('{0} believes it is capable of authenticating this request.'.format(auth))
 141                 auth_candidates.append(auth)
 142
 143         # If we can't find any authentication methods, we should not let them
 144         # pass.
 145         if not auth_candidates:
 146             raise Forbidden()
 147
 148         # For now, just select the first one in the list
 149         auth = auth_candidates[0]
 150
 151         _log.debug('Using {0} to authorize request {1}'.format(
 152             auth, request.url))
 153
 154         if not auth(request, *args, **kw):
 155             if getattr(auth, 'errors', []):
 156                 return json_response({
 157                         'status': 403,
 158                         'errors': auth.errors})
 159
 160             raise Forbidden()
 161
 162         return controller(request, *args, **kw)
 163
 164     return wrapper