oops

Author: e-dard

README.md

@@ -1,20 +1,49 @@
-# rdb
+# netbug
 
-Package `rdb` provides an `http.Handler` for accessing the profiling and debug tools available in the `/net/http/pprof` and `/runtime/pprof` packages.
+[![GoDoc](https://godoc.org/github.com/e-dard/netbug?status.svg)](https://godoc.org/github.com/e-dard/netbug)
 
-The advantages of using `rdb` over the existing `/net/http/pprof` handlers are:
+Package `netbug` provides access to an `http.Handler` that accesses the profiling and debug tools available in the `/net/http/pprof` and `/runtime/pprof` packages.
 
- 1. You can register the handler under an arbitrary route-prefix. A use-case might be to have a secret endpoint for keeping this information hidden from prying eyes on production boxes;
- 2. It pulls together all the handlers from `/net/http/pprof` and `/runtime/pprof` into a single index page, for when you can't quite remember the URL for the profile you want; and
- 3. You can register the handlers onto `http.ServeMux`'s that aren't `http.DefaultServeMux`.
+The advantages of using `netbug` over the existing `/net/http/pprof` handlers are:
+
+ 1. You can register the handler under an arbitrary route-prefix. A use-case might be to have a secret endpoint for keeping this information hidden from prying eyes, rather than `/debug/pprof`;
+ 2. It pulls together all the handlers from `/net/http/pprof` *and* `/runtime/pprof` into a single index page, for when you can't quite remember the URL for the profile you want;
+ 3. You can register the handlers onto `http.ServeMux`'s that aren't `http.DefaultServeMux`;
+ 4. It provides an optional handler that requires a token URL parameter. This is useful if you want that little bit of extra security (use this over HTTPS connections only).
 
 **Note**:
-It still imports `/net/http/pprof`, which means the `/debug/pprof` routes in that package get registered on `http.DefaultServeMux`. If you're using this package to avoid those routes being registered, you should use it with your own `http.ServeMux`.
+It still imports `/net/http/pprof`, which means the `/debug/pprof` routes in that package *still* get registered on `http.DefaultServeMux`.
+If you're using this package to avoid those routes being registered, you should use it with your *own* `http.ServeMux`.
 
-`rdb` is trying to cater for the situation where you want all profiling tools available remotely on your running services, but you don't want to expose the `/debug/pprof` routes that `net/http/pprof` forces you to expose.
+`netbug` is trying to cater for the situation where you want all profiling tools available remotely on your running services, but you don't want to expose the `/debug/pprof` routes that `net/http/pprof` forces you to expose.
 
 ## How do I use it?
-All you have to do is give `rdb` the `http.ServeMux` you want to register the handlers on, and you're away.
+In the simplest case give `netbug` the `http.ServeMux` you want to register the handlers on, as well as where you want to register the handler and you're away.
+
+```go
+package main
+
+import (
+	"log"
+	"net/http"
+
+	"github.com/e-dard/netbug"
+)
+
+func main() {
+	r := http.NewServeMux()
+	rdb.RegisterHandler("/myroute/", r)
+	if err := http.ListenAndServe(":8080", r); err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+Visiting [http://localhost:8080/myroute/](http://localhost:8080/myroute/) will then return:
+
+![](http://f.cl.ly/items/2d13110V2S2H3T1c0n3b/Screen%20Shot%202015-03-19%20at%2017.22.19.png)
+
+`netbug` also provides a simple way of adding some authentication:
 
 ```go
 package main
@@ -23,30 +52,31 @@ import (
 	"log"
 	"net/http"
 
-	"github.com/e-dard/remote-debug"
+	"github.com/e-dard/netbug"
 )
 
 func main() {
 	r := http.NewServeMux()
-	rdb.Register("/some-prefix/", r)
+	rdb.RegisterAuthHandler("password", "/myroute/", r)
 	if err := http.ListenAndServe(":8080", r); err != nil {
 		log.Fatal(err)
 	}
 }
 ```
 
-Visiting `http://localhost:8080/some-prefix/debug/pprof/` will then return:
+And visit [http://localhost:8080/myroute/?token=password](http://localhost:8080/myroute/?token=password).
 
-![](http://cl.ly/image/3x1U3O1B2L3C/Screen%20Shot%202015-03-07%20at%2019.53.28.png)
+**Obviously** this form of authentication is pointless if you're not accessing the routes over an HTTPS connection.
+If you want to use a different form of authentication, e.g., HTTP Basic Authentication, then you can use the handler returned by `netbug.Handler()`, and wrap it with handlers provided by packages like [github.com/abbot/go-http-auth](https://github.com/abbot/go-http-auth/).
 
 ### What can you do with it?
 
-It just wraps the behaviour of the `/net/http/pprof` and `/runtime/pprof` packages.
+It just wraps the behaviour of the [/net/http/pprof](http://golang.org/pkg/net/http/pprof/) and [/runtime/pprof](http://golang.org/pkg/runtime/pprof/) packages.
 Check out their documentation to see what's available.
 As an example though, if you want to run a 30-second CPU profile on your running service it's really simple:
 
 ```
-$ go tool pprof https://example.com/some-hidden-prefix/debug/pprof/profile
+$ go tool pprof https://example.com/myroute/profile
 ```
 
 ## Background
@@ -58,9 +88,11 @@ However, there are a couple of problems with the `net/http/pprof` package.
 
  1. It assumes you're cool about the relevant handlers being registered under the `/debug/pprof` route.
  2. It assumes you're cool about handlers being registered on `http.DefaultServeMux`.
+ 3. You can't wrap the handlers in any way, say to add authentication or other logic.
 
-You can sort of fix (1) and (2) by digging around the `net/http/pprof` package and registering all all the exported handlers under different paths on your own `http.ServeMux`, but you still have the problem of the index page—which is useful to visit if you don't profile much—using hard-coded paths. It doesn't quite work well.
-Also, the index page doesn't provide you with easy links to the debug information that the `net/http/pprof` has handlers for.
+You can sort of fix (1) and (2) by digging around the `net/http/pprof` package and registering all all the exported handlers under different paths on your own `http.ServeMux`, but you still have the problem of the index page—which is useful to visit if you don't profile much—using hard-coded paths.
+It doesn't really work well.
+Also, the index page doesn't provide you with easy links to the debug information that the `net/http/pprof` package has handlers for.
 
-So, `rdb` is just a simple package to fix (1) and (2).
+`netdebug` is just a small package to fix these issues.
 

doc.go

@@ -0,0 +1,103 @@
+// Package netbug provides a http.Handler for executing the various
+// profilers and debug tools in the Go std library.
+//
+// netbug provides some advantages over the /net/http/pprof and
+// /runtime/pprof packages:
+//
+//	1. You can register the handler under an arbitrary route or with
+//	   some authentication on the handler, making it easier to to keep
+//	   the profilers and debug information away from prying eyes;
+//	2. It pulls together all the handlers from /net/http/pprof and
+//	   runtime/pprof into a single index page, for when you can't
+//	   quite remember the URL for the profile you want; and
+//	3. You can register the handler onto an `http.ServeMux` that
+//	   isn't `http.DefaultServeMux`.
+//
+//
+// The simplest integration of netbug looks like:
+//
+//	package main
+//
+//	import (
+//		"log"
+//		"net/http"
+//
+//		"github.com/e-dard/netbug"
+//	)
+//
+//	func main() {
+//		r := http.NewServeMux()
+//		netbug.Register("/myroute/", r)
+//
+//		if err := http.ListenAndServe(":8080", r); err != nil {
+//			log.Fatal(err)
+//		}
+//	}
+//
+// You can then access the index page via GET /myroute/
+//
+// The netbug.RegisterAuthHandler function lets you register the handler on
+// your http.ServeMux and add some simple authentication, in the
+// form of a URL parameter:
+//
+//	package main
+//
+//	import (
+//		"log"
+//		"net/http"
+//
+//		"github.com/e-dard/netbug"
+//	)
+//
+//	func main() {
+//		r := http.NewServeMux()
+//		netbug.RegisterAuthHandler("open sesame", "/myroute/", r)
+//
+//		if err := http.ListenAndServe(":8080", r); err != nil {
+//			log.Fatal(err)
+//		}
+//	}
+//
+// You can then access the index page via GET /myroute/?token=open%20sesame
+//
+// The package also provides access to the handlers directly, for when
+// you want to, say, wrap them in your own logic. Just be sure that
+// when you use the handlers netbug provides you take care to use
+// `http.StripPrefix` to strip the route you register the handler on.
+// This is because the handlers' logic expect them to be registered on
+// "/".
+//
+//	package main
+//
+//	import (
+//		"log"
+//		"net/http"
+//
+//		"github.com/e-dard/netbug"
+//	)
+//
+// 	func myHandler(h http.Handler) http.Handler {
+//		mh := func(w http.ResponseWriter, r *http.Request) {
+//			// Some logic here.
+//			h.ServeHTTP(w, r)
+//		}
+//		return http.HandlerFunc(mh)
+//	}
+//
+//	func main() {
+//		r := http.NewServeMux()
+//		rh := http.StripPrefix("/myroute/", netbug.Handler())
+//		r.Handle("/myroute/", myHandler(rh))
+//
+//		if err := http.ListenAndServe(":8080", r); err != nil {
+//			log.Fatal(err)
+//		}
+//	}
+//
+// As you would expect, netbug works the same way with the go profiler
+// tool as /net/http/pprof does. To run a 30 second CPU profile on your
+// service for example:
+//
+//	$ go tool pprof https://example.com/myroute/profile
+//
+package netbug

netbug.go

@@ -0,0 +1,137 @@
+package netbug
+
+import (
+	"fmt"
+	"log"
+	"net/http"
+	nhpprof "net/http/pprof"
+	"net/url"
+	"runtime/pprof"
+	"strings"
+	"text/template"
+)
+
+func handler(token string) http.Handler {
+	info := struct {
+		Profiles []*pprof.Profile
+		Token    string
+	}{
+		Profiles: pprof.Profiles(),
+		Token:    url.QueryEscape(token),
+	}
+
+	h := func(w http.ResponseWriter, r *http.Request) {
+		name := strings.TrimPrefix(r.URL.Path, "/")
+		switch name {
+		case "":
+			// Index page.
+			if err := indexTmpl.Execute(w, info); err != nil {
+				log.Println(err)
+				return
+			}
+		case "cmdline":
+			nhpprof.Cmdline(w, r)
+		case "profile":
+			nhpprof.Profile(w, r)
+		case "symbol":
+			nhpprof.Symbol(w, r)
+		default:
+			// Provides access to all profiles under runtime/pprof
+			nhpprof.Handler(name).ServeHTTP(w, r)
+		}
+	}
+	return http.HandlerFunc(h)
+}
+
+// Handler returns an http.Handler that provides access to the various
+// profiler and debug tools in the /net/http/pprof and /runtime/pprof
+// packages.
+//
+// The returned handler assumed it is registered on "/" so if you wish
+// to register on any other route, you should strip the route prefix
+// before passing a request on to the handler.
+//
+// This is best done with:
+//
+//	h := http.StripPrefix("/myroute/", netbug.Handler())
+//
+// Unless you need to wrap or chain the handler you probably want to use
+// netbug.RegisterHandler.
+func Handler() http.Handler {
+	return handler("")
+}
+
+// RegisterHandler registers the netbug handler on the provided
+// http.ServeMux, using the provided prefix to form the route.
+//
+// The provided prefix needs to have a trailing slash. The full list of
+// routes registered for available profiles and debug information can
+// be examined by visiting prefix.
+//
+func RegisterHandler(prefix string, mux *http.ServeMux) {
+	mux.Handle(prefix, http.StripPrefix(prefix, Handler()))
+}
+
+// AuthHandler returns an http.Handler that provides authenticated
+// access to the various profiler and debug tools in the
+// /net/http/pprof and /runtime/pprof packages.
+//
+// The token provided is required as a URL parameter called token for
+// all requests. The netbug package takes care of injecting the token
+// into links in the index page.
+//
+// The returned handler assumed it is registered on "/" so if you wish
+// to register on any other route, you should strip the route prefix
+// before passing a request on to the handler.
+//
+// This is best done with:
+//
+//	h := http.StripPrefix("/myroute/", netbug.AuthHandler("secret"))
+//
+// Unless you need to wrap or chain the handler you probably want to use
+// netbug.RegisterAuthHandler.
+func AuthHandler(token string) http.Handler {
+	h := handler(token)
+	ah := func(w http.ResponseWriter, r *http.Request) {
+		if r.FormValue("token") == token {
+			h.ServeHTTP(w, r)
+		} else {
+			w.WriteHeader(http.StatusUnauthorized)
+			fmt.Fprintln(w, "Unauthorized.")
+		}
+	}
+	return http.HandlerFunc(ah)
+}
+
+// RegisterAuthHandler registers a handler requiring authentication on
+// the provided http.ServeMux, using the provided prefix to form the
+// route.
+//
+// The provided prefix needs to have a trailing slash. The full list of
+// routes registered can be examined by visiting the root page.
+func RegisterAuthHandler(token, prefix string, mux *http.ServeMux) {
+	mux.Handle(prefix, http.StripPrefix(prefix, AuthHandler(token)))
+}
+
+var indexTmpl = template.Must(template.New("index").Parse(`<html>
+  <head>
+    <title>Debug Information</title>
+  </head>
+  <br>
+  <body>
+    profiles:<br>
+    <table>
+    {{range .Profiles}}
+      <tr><td align=right>{{.Count}}<td><a href="{{.Name}}?debug=1{{if $.Token}}&token={{$.Token}}{{end}}">{{.Name}}</a>
+    {{end}}
+    <tr><td align=right><td><a href="profile{{if .Token}}?token={{.Token}}{{end}}">CPU</a>
+    </table>
+    <br>
+    debug information:<br>
+    <table>
+      <tr><td align=right><td><a href="cmdline{{if .Token}}?token={{.Token}}{{end}}">cmdline</a>
+      <tr><td align=right><td><a href="symbol{{if .Token}}?token={{.Token}}{{end}}">symbol</a>
+    <tr><td align=right><td><a href="goroutine?debug=2{{if .Token}}&token={{.Token}}{{end}}">full goroutine stack dump</a><br>
+    <table>
+  </body>
+</html>`))