Add withAppEngineService() to package:appengine

lib/appengine.dart

Index: lib/appengine.dart
diff --git a/lib/appengine.dart b/lib/appengine.dart
index 7e77dc908bb7b572798b4656d3878e7b26541989..da74ea8b5d9bad56c3df66f3a0f36b14eb0aacb5 100644
--- a/lib/appengine.dart
+++ b/lib/appengine.dart
@@ -7,13 +7,13 @@ 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';
@@ -69,6 +69,19 @@ Future runAppEngine(AppEngineRequestHandler handler, {Function onError}) {
 }
 
 /**
+ * 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