Documentation ¶
Overview ¶
Package gorca contains common RESTful structures, methods, and functions that are useful go appengine applications.
If you are testing these functions, there are some steps you need to do to setup a proper testing environment.
export APPENGINE_SDK=/path/to/google_appengine cd $GOPATH/src ln -s $APPENGINE_SDK/goroot/src/pkg/appengine ln -s $APPENGINE_SDK/goroot/src/pkg/appengine_internal go get github.com/icub3d/appenginetesting cd github.com/icub3d/gorca go test ./...
Index ¶
- Variables
- func DeleteKeyAndAncestors(c appengine.Context, w http.ResponseWriter, r *http.Request, kind string, ...) bool
- func DeleteKeys(c appengine.Context, w http.ResponseWriter, r *http.Request, ...) bool
- func DeleteStringKeyAndAncestors(c appengine.Context, w http.ResponseWriter, r *http.Request, kind string, ...) bool
- func DeleteStringKeys(c appengine.Context, w http.ResponseWriter, r *http.Request, keys []string) bool
- func GetBodyOrFail(c appengine.Context, w http.ResponseWriter, r *http.Request) ([]byte, bool)
- func GetUserLogoutURL(c appengine.Context, w http.ResponseWriter, r *http.Request, dest string) (string, bool)
- func GetUserOrUnexpected(c appengine.Context, w http.ResponseWriter, r *http.Request) (*user.User, bool)
- func Log(c appengine.Context, r *http.Request, priority string, message string, ...)
- func LogAndFailed(c appengine.Context, w http.ResponseWriter, r *http.Request, err error)
- func LogAndMessage(c appengine.Context, w http.ResponseWriter, r *http.Request, err error, ...)
- func LogAndNotFound(c appengine.Context, w http.ResponseWriter, r *http.Request, err error)
- func LogAndUnexpected(c appengine.Context, w http.ResponseWriter, r *http.Request, err error)
- func NewKey(c appengine.Context, w http.ResponseWriter, r *http.Request, kind string, ...) (string, *datastore.Key, bool)
- func NotFoundFunc(w http.ResponseWriter, r *http.Request)
- func PutKeys(c appengine.Context, w http.ResponseWriter, r *http.Request, ...) bool
- func PutStringKeys(c appengine.Context, w http.ResponseWriter, r *http.Request, keys []string, ...) bool
- func StringToKey(c appengine.Context, w http.ResponseWriter, r *http.Request, key string) (*datastore.Key, bool)
- func StringsToKeys(c appengine.Context, w http.ResponseWriter, r *http.Request, keys []string) ([]*datastore.Key, bool)
- func UnmarshalFromBodyOrFail(c appengine.Context, w http.ResponseWriter, r *http.Request, v interface{}) bool
- func UnmarshalOrFail(c appengine.Context, w http.ResponseWriter, r *http.Request, bytes []byte, ...) bool
- func WriteJSON(c appengine.Context, w http.ResponseWriter, r *http.Request, data interface{})
- func WriteMessage(c appengine.Context, w http.ResponseWriter, r *http.Request, ...)
- func WriteResponse(c appengine.Context, w http.ResponseWriter, r *http.Request, bytes []byte)
- func WriteSuccessMessage(c appengine.Context, w http.ResponseWriter, r *http.Request)
- type Message
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrMsgs map[string]string = map[string]string{
"failed": "Failed.",
"notfound": "Not found.",
"success": "Success.",
"unexpected": "Something unexpected happened.",
"unauthorized": "You are not authorized to do that.",
}
ErrMsgs contains common JSON response messages.
Functions ¶
func DeleteKeyAndAncestors ¶
func DeleteKeyAndAncestors(c appengine.Context, w http.ResponseWriter, r *http.Request, kind string, key *datastore.Key) bool
DeleteKeyAndAncestors is a helper function that remove the given key from the datastore as well as all of it's ancestors of the given kind. If a failure occured, false is returned and a response was returned to the request. This case should be terminal.
func DeleteKeys ¶
func DeleteKeys(c appengine.Context, w http.ResponseWriter, r *http.Request, keys []*datastore.Key) bool
DeleteKeys is a helper function that removes all of the given keys from the datastore. If a failure occured, false is returned and a response was returned to the request. This case should be terminal.
func DeleteStringKeyAndAncestors ¶
func DeleteStringKeyAndAncestors(c appengine.Context, w http.ResponseWriter, r *http.Request, kind string, key string) bool
DeleteStringKeyAndAncestors is a helper function that remove the given key from the datastore as well as all of it's ancestors of the given kind. If a failure occured, false is returned and a response was returned to the request. This case should be terminal.
func DeleteStringKeys ¶
func DeleteStringKeys(c appengine.Context, w http.ResponseWriter, r *http.Request, keys []string) bool
DeleteStringKeys is a helper function that converts the given strings into datastore keys and then calls DeleteKeyHelper on them. If a failure occured, false is returned and a response was returned to the request. This case should be terminal.
func GetBodyOrFail ¶
GetBodyOrFail attempts to read the body from the given request. If it succeeds, the body is returned as a string as well as true. If it fails, "" and false are returned. The failure is also loged and generic error is returned as the response.
func GetUserLogoutURL ¶
func GetUserLogoutURL(c appengine.Context, w http.ResponseWriter, r *http.Request, dest string) (string, bool)
GetUserLogoutURL fetches the currently logged in user's LogoutURL and returns it. The bool returns determines if the get was successful. If not, a JSON "unexpected" message is sent as the response. That case should terminate your response processing.
func GetUserOrUnexpected ¶
func GetUserOrUnexpected(c appengine.Context, w http.ResponseWriter, r *http.Request) (*user.User, bool)
GetUserOrUnexpected fetches the currently logged in user and returns it. The bool returns determines if the get was successful. If not, a JSON "unexpected" message is sent as the response. That case should terminate your response processing.
Example ¶
// Create an appengine context (in this case a mock one). c, err := appenginetesting.NewContext(nil) if err != nil { fmt.Println("creating context", err) return } defer c.Close() // Make the request and writer. w := httptest.NewRecorder() r, err := http.NewRequest("GET", "/example/test", nil) if err != nil { fmt.Println("creating request", err) return } // Get the user (no one is logged in, so it should return an // unexpected). u, ok := GetUserOrUnexpected(c, w, r) if !ok { // Because no one is logged in, we are going to get an unexpected // error.Print out what would be returned down the pipe. fmt.Println("Response Code:", w.Code) fmt.Println("Response Body:", w.Body.String()) } // Now simulate a login and get that user. c.Login("test@example.com", true) u, ok = GetUserOrUnexpected(c, w, r) if !ok { fmt.Println("getting user", err) return } fmt.Println("Logged In User:", u.Email) fmt.Println("Is Admin:", u.Admin)
Output: Response Code: 500 Response Body: {"Type":"error","Message":"Something unexpected happened."} Logged In User: test@example.com Is Admin: true
func Log ¶
func Log(c appengine.Context, r *http.Request, priority string, message string, params ...interface{})
Log is a helper function that logs the given message to appenging with the given priority. Accepted priorities are "debug", "info", "warn", "error", and "crit". Other values default to "error".
func LogAndFailed ¶
LogAndFailed logs the given error message and returns a failed JSON error message as well as a 400.
func LogAndMessage ¶
func LogAndMessage(c appengine.Context, w http.ResponseWriter, r *http.Request, err error, mtype, message string, code int)
LogAndMessage logs the given error (if it is not nil) then sends the given JSON message and status as the response.
func LogAndNotFound ¶
LogAndNotFound logs the given error message and returns a not found JSON error message as well as a 404.
Example ¶
// Note: The LogAnd* functions all work in a similar fashion. // Create an appengine context (in this case a mock one). c, err := appenginetesting.NewContext(nil) if err != nil { fmt.Println("creating context", err) return } defer c.Close() // Make the request and writer. w := httptest.NewRecorder() r, err := http.NewRequest("GET", "/example/test", nil) if err != nil { fmt.Println("creating request", err) return } // Simulate an error err = fmt.Errorf("WHERE ARE THEY TRYING TO GO? LOL") LogAndNotFound(c, w, r, err) // Print out what would be returned down the pipe. fmt.Println("Response Code:", w.Code) fmt.Println("Response Body:", w.Body.String())
Output: Response Code: 404 Response Body: {"Type":"error","Message":"Not found."}
func LogAndUnexpected ¶
LogAndUnexpected logs the given error message and returns an internal server error JSON error message as well as a 500.
func NewKey ¶
func NewKey(c appengine.Context, w http.ResponseWriter, r *http.Request, kind string, parent *datastore.Key) (string, *datastore.Key, bool)
NewKey is a helper function that allocates a new id and uses it to make a new key. It returns both the string and struct version fo the key. If a failure occured, false is returned and a response was returned to the request. This case should be terminal.
func NotFoundFunc ¶
func NotFoundFunc(w http.ResponseWriter, r *http.Request)
NotFoundFunc makes a http.HandlerFunc that returns a standard 404 not found as well as a JSON response with the error.
func PutKeys ¶
func PutKeys(c appengine.Context, w http.ResponseWriter, r *http.Request, keys []*datastore.Key, values interface{}) bool
PutKeys is a helper function the performs a PutMulti on the set of keys and values. If a failure occured, false is returned and a response was returned to the request. This case should be terminal.
func PutStringKeys ¶
func PutStringKeys(c appengine.Context, w http.ResponseWriter, r *http.Request, keys []string, values interface{}) bool
PutStringKeys is a helper function that performs a PutMulti on the set of keys and values. If a failure occured, false is returned and a response was returned to the request. This case should be terminal.
func StringToKey ¶
func StringToKey(c appengine.Context, w http.ResponseWriter, r *http.Request, key string) (*datastore.Key, bool)
StringToKey is a helper function the turns a string into a datastore key. If a failure occured, false is returned and a response was returned to the request. This case should be terminal.
func StringsToKeys ¶
func StringsToKeys(c appengine.Context, w http.ResponseWriter, r *http.Request, keys []string) ([]*datastore.Key, bool)
StringsToKeys is a helper function that turns a list of strings into a list of datastore keys. If a failure occured, false is returned and a response was returned to the request. This case should be terminal.
func UnmarshalFromBodyOrFail ¶
func UnmarshalFromBodyOrFail(c appengine.Context, w http.ResponseWriter, r *http.Request, v interface{}) bool
UnmarshalFromBodyOrFail attempts to read the body from the given request and umarshal it as JSON into the given interface. If an error occurs, the failure is logged and a generic message is returned as the response. The boolean value returned signifies the success of the operation.
func UnmarshalOrFail ¶
func UnmarshalOrFail(c appengine.Context, w http.ResponseWriter, r *http.Request, bytes []byte, where interface{}) bool
UnmarshalOrFail attempts to unmarshal the given bytes as JSON and put it in where. if it fails, false is returned and a "failed" message is returned. In that case, this should be terminal.
func WriteJSON ¶
WriteJSON transforms the given data into JSON and sends it as a response. If an error occurs, that will be returned instead.
func WriteMessage ¶
func WriteMessage(c appengine.Context, w http.ResponseWriter, r *http.Request, mtype, message string, code int)
WriteMessage prints a standard JSON message to the given writer.
func WriteResponse ¶
WriteResponse writes the given data to the given response write. If an error occurs, it is logged.
func WriteSuccessMessage ¶
WriteSuccessMessage prints a JSON response of success to the given writer.