Add withAppEngineService() to package:appengine

lib/appengine.dart

 // Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 library appengine;
 
 import 'dart:async';
 import 'dart:io';
 
+export 'package:gcloud/http.dart';
 import 'package:gcloud/service_scope.dart' as ss;
 
 import 'src/appengine_internal.dart' as appengine_internal;
 import 'src/app_engine_request_handler.dart';
 import 'src/client_context.dart';
 
-export 'package:gcloud/http.dart';
 export 'api/errors.dart';
 export 'api/logging.dart';
 export 'api/modules.dart';
 export 'api/memcache.dart';
 export 'api/remote_api.dart';
 export 'api/users.dart';
 export 'src/app_engine_request_handler.dart';
 export 'src/client_context.dart';
 
 const Symbol _APPENGINE_CONTEXT = #_appengine.context;
@@ skipping 35 matching lines @@
   }
 
   return appengine_internal.runAppEngine((HttpRequest request,
                                           ClientContext context) {
     ss.register(_APPENGINE_CONTEXT, context);
     handler(request);
   }, errorHandler);
 }
 
 /**
+ * Runs [callback] inside a new service scope with appengine services added.
+ *
+ * The services available to `callback` are all non-request specific appengine
+ * services e.g. `memcacheService`, `dbService`.
+ *
+ * See `package:gcloud/service_scope.dart` for more information on service
+ * scopes.

[Søren Gjesse, 2014/12/03 11:17:42]

Please add the example from the code-review here.

Need some more information on the returned Future.

Can we add a future in the package which completes when shutting dowm. That way
we can suggest that that future is returned, e.g.

withAppEngineServices(() {
  // Startup stuff.

  // done is a global Future in the appengine package (should be called
something else).
  return done;
)}

This can also be done to run a "one shot" function after starting App Engine,
like this:

runAppEngine(..).then((_) {
  withAppEngineServices(() {
    // Do something, e.g. log startup info.
    return new Future.value();
  });
});

[kustermann, 2014/12/03 11:55:29]

Done -- added sample code.

Actually I think it's better if `runAppEngine()` just completes when we shut
down (which it actually does with this CL).

I like that much more. Then people can do cleanup when the request handling is
done, e.g. something like

main() {
  withAppEngineServics(() {
    return runAppEngine(handler).whenComplete(() {
      // Save global state, before shutting down VM.
      return dbService.commit(temporaryGlobalState);
    });
  });
}

[I think this is better than having a global done Future].


On the other hand it might be more complicated, if AppEngine will kill the VM
immediately after sending /_ah/stop, because then we would need to hold the
response back before completing. In which case we need something like:
registerShutdownHook() or something like that.

But this is orthogonal to the global done future vs. `runAppEngine()` Future.

[Søren Gjesse, 2014/12/03 13:09:01]

In principle I am fine with this change to what the Future returned by
runAppEngine means. But it needs to be clearly documented. I think there will be
some time from /_ah/stop is called until the VM is killed. The documentation
says:

The stop lifecycle event is sent to your application when App Engine is
preparing to turn down the container. It is signaled as a HTTP request to the
handler /_ah/stop. The application does not need to respond to this event - but
can use it to perform any necessary clean up actions prior to the container
being shut down.

+ */
+Future withAppEngineServices(Future callback()) {
+  return appengine_internal.withAppEngineServices(callback);
+}
+
+/**
  * Returns the [ClientContext] of the current request.
  *
  * This getter can only be called inside a request handler which was passed to
  * [runAppEngine].
  */
 ClientContext get context => ss.lookup(_APPENGINE_CONTEXT);