ref: Refactor watcher system to use genericWatcher; improve project d…

…ocumentation (#20)

* Refactor watcher system to use genericWatcher; improve docs

* oops

* Add examples to package docs

README.md

@@ -92,6 +92,8 @@ func main() {
 }
 ```
 
+For more examples, visit the [examples directory](./examples).
+
 ## Documentation
 
 See [godoc](https://pkg.go.dev/github.com/linode/go-metadata) for a complete documentation reference.

doc.go

@@ -0,0 +1,36 @@
+/*
+go-metadata allows Go projects to easily interact with the Linode Metadata Service.
+
+Basic example:
+	package main
+
+	import (
+		"context"
+		"fmt"
+		"log"
+
+		metadata "github.com/linode/go-metadata"
+	)
+
+	func main() {
+		// Create a new client
+		client, err := metadata.NewClient(context.Background())
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		// Retrieve metadata about the current instance from the metadata API
+		instanceInfo, err := client.GetInstance(context.Background())
+		if err != nil {
+			log.Fatal(err)
+		}
+
+		fmt.Println("Instance Label:", instanceInfo.Label)
+	}
+
+For more examples see: https://github.com/linode/go-metadata/tree/ref/watcher-refactor/examples
+
+To learn more about the Linode Metadata Service, see the official guide: https://www.linode.com/docs/products/compute/compute-instances/guides/metadata/?tabs=linode-api
+*/
+
+package metadata

examples/README.md

@@ -0,0 +1,6 @@
+# go-metadata Examples
+
+This directory contains various runnable examples for using this package.
+
+- [Instance Watcher](./instancewatcher) - Watch for changes to the current Linode instance.
+- [Network Watcher](./networkwatcher) - Watch for changes to the current Linode instance's networking.

examples/instancewatcher/README.md

@@ -0,0 +1,11 @@
+# Instance Watcher Example
+
+This example makes use of the InstanceWatcher struct to watch for changes to the current Linode instance.
+
+### Running this Example
+
+NOTE: This example must be run from within a Linode instance.
+
+```bash
+go run main.go
+```

examples/instancewatcher/main.go

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"context"
+	metadata "github.com/linode/go-metadata"
+	"log"
+	"time"
+)
+
+func main() {
+	ctx := context.Background()
+
+	// Create a new client
+	client, err := metadata.NewClient(ctx)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Create a new instance watcher
+	instanceWatcher := client.NewInstanceWatcher(
+		metadata.WatcherWithInterval(10 * time.Second),
+	)
+
+	// Start the network watcher in a goroutine.
+	go instanceWatcher.Start(ctx)
+
+	// Wait for changes
+	for {
+		select {
+		case data := <-instanceWatcher.Updates:
+			log.Printf(
+				"Change to instance detected.\nNew data: %v\n",
+				data,
+			)
+		case err := <-instanceWatcher.Errors:
+			log.Fatalf("Got error from instance watcher: %s", err)
+		}
+	}
+}

examples/networkwatcher/README.md

@@ -0,0 +1,11 @@
+# Network Watcher Example
+
+This example makes use of the NetworkWatcher struct to watch for changes to the current Linode instance's networking.
+
+### Running this Example
+
+NOTE: This example must be run from within a Linode instance.
+
+```bash
+go run main.go
+```

examples/networkwatcher/main.go

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"context"
+	metadata "github.com/linode/go-metadata"
+	"log"
+	"time"
+)
+
+func main() {
+	ctx := context.Background()
+
+	// Create a new client
+	client, err := metadata.NewClient(ctx)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Create a new network watcher
+	networkWatcher := client.NewNetworkWatcher(
+		metadata.WatcherWithInterval(10 * time.Second),
+	)
+
+	// Start the network watcher in a goroutine.
+	go networkWatcher.Start(ctx)
+
+	// Wait for changes
+	for {
+		select {
+		case data := <-networkWatcher.Updates:
+			log.Printf(
+				"Change to network configuration detected.\nNew data: %v\n",
+				data,
+			)
+		case err := <-networkWatcher.Errors:
+			log.Fatalf("Got error from network watcher: %s", err)
+		}
+	}
+}

test/integration/watcher_test.go

@@ -56,7 +56,7 @@ func TestNetworkWatcher(t *testing.T) {
 	assert.NoError(t, err)
 
 	watcher := metadataClient.NewNetworkWatcher(metadata.WatcherWithInterval(1 * time.Second))
-	watcher.Start(ctx)
+	go watcher.Start(ctx)
 	numUpdates := 0
 	for i := 1; i <= 5; i++ {
 		updateData := <-watcher.Updates
@@ -116,7 +116,7 @@ func TestInstanceWatcher(t *testing.T) {
 	assert.NoError(t, err)
 
 	watcher := metadataClient.NewInstanceWatcher(metadata.WatcherWithInterval(1 * time.Second))
-	watcher.Start(ctx)
+	go watcher.Start(ctx)
 	numUpdates := 0
 	for i := 1; i <= 5; i++ {
 		updateData := <-watcher.Updates