google_appengine/google/appengine/ext/remote_api/handler.py

   1 #!/usr/bin/env python
   2 #
   3 # Copyright 2007 Google Inc.
   4 #
   5 # Licensed under the Apache License, Version 2.0 (the "License");
   6 # you may not use this file except in compliance with the License.
   7 # You may obtain a copy of the License at
   8 #
   9 #     http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing, software
  12 # distributed under the License is distributed on an "AS IS" BASIS,
  13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 # See the License for the specific language governing permissions and
  15 # limitations under the License.
  16 #
  17
  18 """A handler that exports various App Engine services over HTTP.
  19
  20 You can export this handler in your app by adding it directly to app.yaml's
  21 list of handlers:
  22
  23   handlers:
  24   - url: /remote_api
  25     script: $PYTHON_LIB/google/appengine/ext/remote_api/handler.py
  26     login: admin
  27
  28 Then, you can use remote_api_stub to remotely access services exported by this
  29 handler. See the documentation in remote_api_stub.py for details on how to do
  30 this.
  31
  32 Using this handler without specifying "login: admin" would be extremely unwise.
  33 So unwise that the default handler insists on checking for itself.
  34 """
  35
  36
  37
  38
  39
  40 import google
  41 import logging
  42 import os
  43 import pickle
  44 import sha
  45 import sys
  46 import wsgiref.handlers
  47 import yaml
  48
  49 from google.appengine.api import api_base_pb
  50 from google.appengine.api import apiproxy_stub
  51 from google.appengine.api import apiproxy_stub_map
  52 from google.appengine.api import users
  53 from google.appengine.datastore import datastore_pb
  54 from google.appengine.ext import webapp
  55 from google.appengine.ext.remote_api import remote_api_pb
  56 from google.appengine.ext.remote_api import remote_api_services
  57 from google.appengine.runtime import apiproxy_errors
  58
  59
  60 class RemoteDatastoreStub(apiproxy_stub.APIProxyStub):
  61   """Provides a stub that permits execution of stateful datastore queries.
  62
  63   Some operations aren't possible using the standard interface. Notably,
  64   datastore RunQuery operations internally store a cursor that is referenced in
  65   later Next calls, and cleaned up at the end of each request. Because every
  66   call to ApiCallHandler takes place in its own request, this isn't possible.
  67
  68   To work around this, RemoteDatastoreStub provides its own implementation of
  69   RunQuery that immediately returns the query results.
  70   """
  71
  72   def __init__(self, service='datastore_v3', _test_stub_map=None):
  73     """Constructor.
  74
  75     Args:
  76       service: The name of the service
  77       _test_stub_map: An APIProxyStubMap to use for testing purposes.
  78     """
  79     super(RemoteDatastoreStub, self).__init__(service)
  80     if _test_stub_map:
  81       self.__call = _test_stub_map.MakeSyncCall
  82     else:
  83       self.__call = apiproxy_stub_map.MakeSyncCall
  84
  85   def _Dynamic_RunQuery(self, request, response):
  86     """Handle a RunQuery request.
  87
  88     We handle RunQuery by executing a Query and a Next and returning the result
  89     of the Next request.
  90
  91     This method is DEPRECATED, but left in place for older clients.
  92     """
  93     runquery_response = datastore_pb.QueryResult()
  94     self.__call('datastore_v3', 'RunQuery', request, runquery_response)
  95     if runquery_response.result_size() > 0:
  96       response.CopyFrom(runquery_response)
  97       return
  98
  99     next_request = datastore_pb.NextRequest()
 100     next_request.mutable_cursor().CopyFrom(runquery_response.cursor())
 101     next_request.set_count(request.limit())
 102     self.__call('datastore_v3', 'Next', next_request, response)
 103
 104   def _Dynamic_Transaction(self, request, response):
 105     """Handle a Transaction request.
 106
 107     We handle transactions by accumulating Put requests on the client end, as
 108     well as recording the key and hash of Get requests. When Commit is called,
 109     Transaction is invoked, which verifies that all the entities in the
 110     precondition list still exist and their hashes match, then performs a
 111     transaction of its own to make the updates.
 112     """
 113     begin_request = datastore_pb.BeginTransactionRequest()
 114     begin_request.set_app(os.environ['APPLICATION_ID'])
 115     tx = datastore_pb.Transaction()
 116     self.__call('datastore_v3', 'BeginTransaction', begin_request, tx)
 117
 118     preconditions = request.precondition_list()
 119     if preconditions:
 120       get_request = datastore_pb.GetRequest()
 121       get_request.mutable_transaction().CopyFrom(tx)
 122       for precondition in preconditions:
 123         key = get_request.add_key()
 124         key.CopyFrom(precondition.key())
 125       get_response = datastore_pb.GetResponse()
 126       self.__call('datastore_v3', 'Get', get_request, get_response)
 127       entities = get_response.entity_list()
 128       assert len(entities) == request.precondition_size()
 129       for precondition, entity in zip(preconditions, entities):
 130         if precondition.has_hash() != entity.has_entity():
 131           raise apiproxy_errors.ApplicationError(
 132               datastore_pb.Error.CONCURRENT_TRANSACTION,
 133               "Transaction precondition failed.")
 134         elif entity.has_entity():
 135           entity_hash = sha.new(entity.entity().Encode()).digest()
 136           if precondition.hash() != entity_hash:
 137             raise apiproxy_errors.ApplicationError(
 138                 datastore_pb.Error.CONCURRENT_TRANSACTION,
 139                 "Transaction precondition failed.")
 140
 141     if request.has_puts():
 142       put_request = request.puts()
 143       put_request.mutable_transaction().CopyFrom(tx)
 144       self.__call('datastore_v3', 'Put', put_request, response)
 145
 146     if request.has_deletes():
 147       delete_request = request.deletes()
 148       delete_request.mutable_transaction().CopyFrom(tx)
 149       self.__call('datastore_v3', 'Delete', delete_request,
 150                  api_base_pb.VoidProto())
 151
 152     self.__call('datastore_v3', 'Commit', tx, api_base_pb.VoidProto())
 153
 154   def _Dynamic_GetIDs(self, request, response):
 155     """Fetch unique IDs for a set of paths."""
 156     for entity in request.entity_list():
 157       assert entity.property_size() == 0
 158       assert entity.raw_property_size() == 0
 159       assert entity.entity_group().element_size() == 0
 160       lastpart = entity.key().path().element_list()[-1]
 161       assert lastpart.id() == 0 and not lastpart.has_name()
 162
 163     begin_request = datastore_pb.BeginTransactionRequest()
 164     begin_request.set_app(os.environ['APPLICATION_ID'])
 165     tx = datastore_pb.Transaction()
 166     self.__call('datastore_v3', 'BeginTransaction', begin_request, tx)
 167
 168     self.__call('datastore_v3', 'Put', request, response)
 169
 170     self.__call('datastore_v3', 'Rollback', tx, api_base_pb.VoidProto())
 171
 172
 173 SERVICE_PB_MAP = remote_api_services.SERVICE_PB_MAP
 174
 175 class ApiCallHandler(webapp.RequestHandler):
 176   """A webapp handler that accepts API calls over HTTP and executes them."""
 177
 178   LOCAL_STUBS = {
 179       'remote_datastore': RemoteDatastoreStub('remote_datastore'),
 180   }
 181
 182   def CheckIsAdmin(self):
 183     if not users.is_current_user_admin():
 184       self.response.set_status(401)
 185       self.response.out.write(
 186           "You must be logged in as an administrator to access this.")
 187       self.response.headers['Content-Type'] = 'text/plain'
 188       return False
 189     elif 'X-appcfg-api-version' not in self.request.headers:
 190       self.response.set_status(403)
 191       self.response.out.write("This request did not contain a necessary header")
 192       self.response.headers['Content-Type'] = 'text/plain'
 193       return False
 194     return True
 195
 196
 197   def get(self):
 198     """Handle a GET. Just show an info page."""
 199     if not self.CheckIsAdmin():
 200       return
 201
 202     rtok = self.request.get('rtok', '0')
 203     app_info = {
 204         'app_id': os.environ['APPLICATION_ID'],
 205         'rtok': rtok
 206         }
 207
 208     self.response.headers['Content-Type'] = 'text/plain'
 209     self.response.out.write(yaml.dump(app_info))
 210
 211   def post(self):
 212     """Handle POST requests by executing the API call."""
 213     if not self.CheckIsAdmin():
 214       return
 215
 216     self.response.headers['Content-Type'] = 'application/octet-stream'
 217     response = remote_api_pb.Response()
 218     try:
 219       request = remote_api_pb.Request()
 220       request.ParseFromString(self.request.body)
 221       response_data = self.ExecuteRequest(request)
 222       response.mutable_response().set_contents(response_data.Encode())
 223       self.response.set_status(200)
 224     except Exception, e:
 225       logging.exception('Exception while handling %s', request)
 226       self.response.set_status(200)
 227       response.mutable_exception().set_contents(pickle.dumps(e))
 228       if isinstance(e, apiproxy_errors.ApplicationError):
 229         application_error = response.mutable_application_error()
 230         application_error.set_code(e.application_error)
 231         application_error.set_detail(e.error_detail)
 232     self.response.out.write(response.Encode())
 233
 234   def ExecuteRequest(self, request):
 235     """Executes an API invocation and returns the response object."""
 236     service = request.service_name()
 237     method = request.method()
 238     service_methods = SERVICE_PB_MAP.get(service, {})
 239     request_class, response_class = service_methods.get(method, (None, None))
 240     if not request_class:
 241       raise apiproxy_errors.CallNotFoundError()
 242
 243     request_data = request_class()
 244     request_data.ParseFromString(request.request().contents())
 245     response_data = response_class()
 246
 247     if service in self.LOCAL_STUBS:
 248       self.LOCAL_STUBS[service].MakeSyncCall(service, method, request_data,
 249                                              response_data)
 250     else:
 251       apiproxy_stub_map.MakeSyncCall(service, method, request_data,
 252                                      response_data)
 253
 254     return response_data
 255
 256   def InfoPage(self):
 257     """Renders an information page."""
 258     return """
 259 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
 260  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 261 <html><head>
 262 <title>App Engine API endpoint.</title>
 263 </head><body>
 264 <h1>App Engine API endpoint.</h1>
 265 <p>This is an endpoint for the App Engine remote API interface.
 266 Point your stubs (google.appengine.ext.remote_api.remote_api_stub) here.</p>
 267 </body>
 268 </html>"""
 269
 270
 271 def main():
 272   application = webapp.WSGIApplication([('.*', ApiCallHandler)])
 273   wsgiref.handlers.CGIHandler().run(application)
 274
 275
 276 if __name__ == '__main__':
 277   main()