Merge pull request #11 from signalsciences/example-updates

Example updates

Author: brectanus-sigsci

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+* Updated helloworld example to be more configurable allowing it to be used in other example documentation
+
 ## 1.6.2 2019-08-25
 
 * Added support for a custom header extractor fn

README.md

@@ -5,7 +5,7 @@
 
 The Signal Sciences module in Golang allows for integrating your Golang
 application directly with the Signal Sciences agent at the source code
-level. It is written as an `http.Handler` wrapper. To
+level. It is written as a `http.Handler` wrapper. To
 integrate your application with the module, you will need to wrap your
 existing handler with the module handler.
 
@@ -14,7 +14,7 @@ existing handler with the module handler.
 
 ## Example Code Snippet
 ```go
-// Existing http.Handler
+// Example existing http.Handler
 mux := http.NewServeMux()
 mux.HandleFunc("/", helloworld)
 
@@ -44,26 +44,24 @@ log.Fatal(s.ListenAndServe())
 
 ## Examples
 
-The [examples](examples/) directory contains complete example code.
+The [examples/helloworld](examples/helloworld) directory contains complete example code.
 
 To run the simple [helloworld](examples/helloworld/main.go) example:
-
-```bash
-go run examples/helloworld/main.go
-```
-
-Or, if your agent is running with a non-default `rpc-address`, you can
-pass the sigsci-agent address as an argument such as one of the following:
-
-```bash
-# Another UNIX Domain socket
-go run examples/helloworld/main.go /tmp/sigsci.sock
-# A TCP address:port
-go run examples/helloworld/main.go localhost:9999
+```shell
+# Syntax:
+#   go run ./examples/helloworld <listener-address:port> [<sigsci-agent-rpc-address>]
+#
+# Run WITHOUT sigsci enabled
+go run ./examples/helloworld localhost:8000
+# Run WITH sigsci-agent listening via a UNIX Domain socket file
+go run ./examples/helloworld localhost:8000 /var/run/sigsci.sock
+# Run WITH sigsci-agent listening via a TCP address:port
+go run ./examples/helloworld localhost:8000 localhost:9999
 ```
 
-This will run an HTTP listener on `localhost:8000`, which will send any
-traffic to this listener to a running sigsci-agent for inspection.
+The above will run a HTTP listener on `localhost:8000`, which will send any
+traffic to this listener to a running sigsci-agent for inspection (if
+an agent address is configured).
 
 [doc-img]: https://godoc.org/github.com/signalsciences/sigsci-module-golang?status.svg
 [doc]: https://godoc.org/github.com/signalsciences/sigsci-module-golang

examples/helloworld/main.go

@@ -11,45 +11,61 @@ import (
 )
 
 func main() {
-	// Process sigsci-agent rpc-address if passed
-	sigsciAgentNetwork := "unix"
-	sigsciAgentAddress := "/var/run/sigsci.sock"
+	// Get the listener address from the first arg
+	listenerAddress := ""
 	if len(os.Args) > 1 {
-		sigsciAgentAddress = os.Args[1]
+		listenerAddress = os.Args[1]
+	}
+	if len(listenerAddress) == 0 {
+		listenerAddress = "localhost:8000"
+	}
+
+	// Process sigsci-agent rpc-address from the optional second arg
+	sigsciAgentNetwork := "unix"
+	sigsciAgentAddress := ""
+	if len(os.Args) > 2 {
+		sigsciAgentAddress = os.Args[2]
 	}
 	if !strings.Contains(sigsciAgentAddress, "/") {
 		sigsciAgentNetwork = "tcp"
 	}
-	log.Printf("Using sigsci-agent address (pass address as program argument to change): %s:%s", sigsciAgentNetwork, sigsciAgentAddress)
 
 	// Existing handler, in this case a simple http.ServeMux,
 	// but could be any http.Handler in the application
 	mux := http.NewServeMux()
 	mux.HandleFunc("/", helloworld)
+	handler := http.Handler(mux)
+
+	if len(sigsciAgentAddress) > 0 {
+		// Wrap the existing http.Handler with the SigSci module handler
+		wrapped, err := sigsci.NewModule(
+			// Existing handler to wrap
+			mux,
+
+			// Any additional module options:
+			sigsci.Socket(sigsciAgentNetwork, sigsciAgentAddress),
+			//sigsci.Timeout(100 * time.Millisecond),
+			//sigsci.AnomalySize(512 * 1024),
+			//sigsci.AnomalyDuration(1 * time.Second),
+			//sigsci.MaxContentLength(100000),
 
-	// Wrap the existing http.Handler with the SigSci module handler
-	wrapped, err := sigsci.NewModule(
-		// Existing handler to wrap
-		mux,
+			// Turn on debug logging for this example (do not use in production)
+			sigsci.Debug(true),
+		)
+		if err != nil {
+			log.Fatal(err)
+		}
 
-		// Any additional module options:
-		sigsci.Socket(sigsciAgentNetwork, sigsciAgentAddress),
-		//sigsci.Timeout(100 * time.Millisecond),
-		//sigsci.AnomalySize(512 * 1024),
-		//sigsci.AnomalyDuration(1 * time.Second),
-		//sigsci.MaxContentLength(100000),
+		log.Printf("Signal Sciences agent RPC address: %s:%s", sigsciAgentNetwork, sigsciAgentAddress)
 
-		// Turn on debug logging for this example (do not use in production)
-		sigsci.Debug(true),
-	)
-	if err != nil {
-		log.Fatal(err)
+		// Use the wrapped sigsci handler
+		handler = wrapped
 	}
 
-	// Listen and Serve as usual using the wrapped sigsci handler
+	// Listen and Serve as usual using the wrapped sigsci handler if enabled
 	s := &http.Server{
-		Handler: wrapped,
-		Addr:    "localhost:8000",
+		Handler: handler,
+		Addr:    listenerAddress,
 	}
 	log.Printf("Server URL: http://%s/", s.Addr)
 	log.Fatal(s.ListenAndServe())