impl/prod: Make AEContext private.

impl/prod/context.go

 // Copyright 2015 The LUCI Authors. All rights reserved.
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
 package prod
 
 import (
         "fmt"
         "net/http"
         "net/http/cookiejar"
@@ skipping 14 matching lines @@
         "https://www.googleapis.com/auth/cloud.platform",
 }
 
 type key int
 
 var (
         prodStateKey  = "contains the current *prodState"
         probeCacheKey = "contains the current *infoProbeCache"
 )
 
-// AEContext retrieves the raw "google.golang.org/appengine" compatible Context.
+// getAEContext retrieves the raw "google.golang.org/appengine" compatible
+// Context.
 //
-// It also transfers deadline of `c` to AE context, since deadline is used for
-// RPCs. Doesn't transfer cancelation ability though (since it's ignored by GAE
-// anyway).
-func AEContext(c context.Context) context.Context {
+// This is an independent Context chain from `c`. In an attempt to maintain user
+// expectations, the deadline of `c` is transferred to the returned Context,
+// RPCs. Cancelation is not transferred.
+func getAEContext(c context.Context) context.Context {
         ps := getProdState(c)
         return ps.context(c)
 }
 
 func setupAECtx(c, aeCtx context.Context) context.Context {
         c = withProdState(c, prodState{
                 ctx:      aeCtx,
                 noTxnCtx: aeCtx,
         })
         return useModule(useMail(useUser(useURLFetch(useRDS(useMC(useTQ(useGI(useLogging(c)))))))))
 }
 
 // Use adds production implementations for all the gae services to the
-// context.
+// context. The implementations are all backed by the real appengine SDK
+// functionality.
 //
 // The services added are:
 //   - github.com/luci-go/common/logging
 //   - github.com/luci/gae/service/datastore
 //   - github.com/luci/gae/service/info
 //   - github.com/luci/gae/service/mail
 //   - github.com/luci/gae/service/memcache
 //   - github.com/luci/gae/service/module
 //   - github.com/luci/gae/service/taskqueue
 //   - github.com/luci/gae/service/urlfetch
 //   - github.com/luci/gae/service/user
 //
 // These can be retrieved with the <service>.Get functions.
 //
-// The implementations are all backed by the real appengine SDK functionality,
+// It is important to note that this DOES NOT install the AppEngine SDK into the
+// supplied Context. In general, using the raw AppEngine SDK to access a service
+// that is covered by luci/gae is dangerous, leading to a number of potential
+// pitfalls including inconsistent transaction management and data corruption.
+//
+// Users who wish to access the raw AppEngine SDK must derive their own
+// AppEngine Context at their own risk.
 func Use(c context.Context, r *http.Request) context.Context {
         return setupAECtx(c, appengine.NewContext(r))
 }
 
 // UseRemote is the same as Use, except that it lets you attach a context to
 // a remote host using the Remote API feature. See the docs for the
 // prerequisites.
 //
 // docs: https://cloud.google.com/appengine/docs/go/tools/remoteapi
 //
 // inOutCtx will be replaced with the new, derived context, if err is nil,
 // otherwise it's unchanged and continues to be safe-to-use.
 //
 // If client is nil, this will use create a new client, and will try to be
 // clever about it:
 //   * If you're creating a remote context FROM AppEngine, this will use
 //     urlfetch.Transport. This can be used to allow app-to-app remote_api
 //     control.
 //
 //   * If host starts with "localhost", this will create a regular http.Client
 //     with a cookiejar, and call the _ah/login API to log in as an admin with
 //     the user "admin@example.com".
 //
 //   * Otherwise, it will create a Google OAuth2 client with the following scopes:
 //       - "https://www.googleapis.com/auth/appengine.apis"
 //       - "https://www.googleapis.com/auth/userinfo.email"
 //       - "https://www.googleapis.com/auth/cloud.platform"
+//
+// It is important to note that this DOES NOT install the AppEngine SDK into the
+// supplied Context. See the warning in Use for more information.
 func UseRemote(inOutCtx *context.Context, host string, client *http.Client) (err error) {
         if client == nil {
-                aeCtx := AEContext(*inOutCtx)
+                aeCtx := getAEContext(*inOutCtx)
 
                 if strings.HasPrefix(host, "localhost") {
                         transp := http.DefaultTransport
                         if aeCtx != nil {
                                 transp = urlfetch.Get(*inOutCtx)
                         }
 
                         client = &http.Client{Transport: transp}
                         client.Jar, err = cookiejar.New(nil)
                         if err != nil {
@@ skipping 67 matching lines @@
         aeCtx := ps.ctx
         if aeCtx == nil {
                 return nil
         }
 
         if deadline, ok := c.Deadline(); ok {
                 aeCtx, _ = context.WithDeadline(aeCtx, deadline)
         }
         return aeCtx
 }