Apply suggestions from code review

Co-authored-by: Jye Cusch <[email protected]>
Simplify project so it doesn't need an update to the nitric.yaml config.

Simplify project so it doesn't need an update to the nitric.yaml config.

handle errors and add consistency between guides

Author: raksiv

docs/guides/go/realtime-messaging.mdx

@@ -1,16 +1,15 @@
 ---
-title_seo: Building your first WebSocket Application with Go and Nitric
 description: Use the Nitric framework to easily build and deploy Go WebSocket applications for AWS.
 tags:
   - Realtime & Websockets
   - Key Value Store
 ---
 
-# Building your first WebSocket Application with Nitric
+# Building a chat app in Go with WebSockets and Nitric
 
 ## What we'll be doing
 
-1. Use Nitric to create a WebSocket endpoint
+1. Use Nitric to create a WebSocket API
 2. Manage WebSocket connections using a Key-Value store
 3. Handle WebSocket events:
    - Register connections on connect
@@ -23,20 +22,20 @@ tags:
 
 - [Go](https://go.dev/dl/)
 - The [Nitric CLI](/get-started/installation)
-- An [AWS](https://aws.amazon.com) account
+- An [AWS](https://aws.amazon.com) account (optional)
 
 ## Getting started
 
 We'll start by creating a new project for our WebSocket application.
 
 ```bash
-nitric new my-websocket-app go-starter
+nitric new websocket-app go-starter
 ```
 
 Next, open the project in your editor of choice.
 
 ```bash
-cd my-websocket-app
+cd websocket-app
 ```
 
 Make sure all dependencies are resolved:
@@ -69,9 +68,9 @@ If everything is working as expected, you can now delete all files/folders in th
 
 ## Building the WebSocket Application
 
-Let's begin by setting up the WebSocket application. First, create a new folder called `websockets` within the services directory. Inside this folder, add a file named `main.go`, and include the following code:
+Let's begin by setting up the WebSocket application. Add a file named `main.go` to your 'services/websockets' folder, and include the following code:
 
-```go
+```go title:services/websockets/main.go
 package main
 
 import (
@@ -84,7 +83,7 @@ import (
 )
 
 func main() {
-  // Create a WebSocket endpoint named "public".
+  // Create a WebSocket API named "public".
   ws := nitric.NewWebsocket("public")
 
   // Initialize a KV store named "connections" with Get, Set, and Delete permissions.
@@ -98,8 +97,8 @@ func main() {
 
 Here we're creating:
 
-- A [WebSocket](/websockets) endpoint named `public`
-- A [Key-Value store](/keyvalue) named `connections` to track WebSocket connections
+- A [WebSocket](/websockets) API named `public`
+- A [Key-Value store](/keyvalue) named `connections` to track client connections
 
 From here, let's add some features to that function that allow us to manage connections and broadcast messages.
 
@@ -112,10 +111,11 @@ From here, let's add some features to that function that allow us to manage conn
 
 ```go
 ws.On(websockets.EventType_Connect, func(ctx *websockets.Ctx) {
-  err := connections.Set(context.TODO(), ctx.Request.ConnectionID(), map[string]interface{}{
+  err := connections.Set(context.Background(), ctx.Request.ConnectionID(), map[string]interface{}{
     "connectionId": ctx.Request.ConnectionID(),
   })
   if err != nil {
+    fmt.Println("Error storing connection ID in KV store:", err)
     return
   }
 })
@@ -125,8 +125,9 @@ ws.On(websockets.EventType_Connect, func(ctx *websockets.Ctx) {
 
 ```go
 ws.On(websockets.EventType_Disconnect, func(ctx *websockets.Ctx) {
-  err := connections.Delete(context.TODO(), ctx.Request.ConnectionID())
+  err := connections.Delete(context.Background(), ctx.Request.ConnectionID())
   if err != nil {
+    fmt.Println("Error deleting connection ID in KV store:", err)
     return
   }
 })
@@ -136,8 +137,9 @@ ws.On(websockets.EventType_Disconnect, func(ctx *websockets.Ctx) {
 
 ```go
 ws.On(websockets.EventType_Message, func(ctx *websockets.Ctx) {
-  connectionStream, err := connections.Keys(context.TODO())
+  connectionStream, err := connections.Keys(context.Background())
   if err != nil {
+    fmt.Println("Error retrieving connection keys from KV store:", err)
     return
   }
 
@@ -154,8 +156,9 @@ ws.On(websockets.EventType_Message, func(ctx *websockets.Ctx) {
     }
 
     message := fmt.Sprintf("%s: %s", senderId, ctx.Request.Message())
-    err = ws.Send(context.TODO(), connectionId, []byte(message))
+    err = ws.Send(context.Background(), connectionId, []byte(message))
     if err != nil {
+      fmt.Println("Error sending message to connection ID", connectionId, ":", err)
       return
     }
   }
@@ -167,7 +170,7 @@ ws.On(websockets.EventType_Message, func(ctx *websockets.Ctx) {
 <details>
 <summary>Your code should look like this:</summary>
 
-```go
+```go title:services/websockets/main.go
 package main
 
 import (
@@ -188,24 +191,27 @@ func main() {
 
   // Handle new WebSocket connections by storing the connection ID in the KV store.
   ws.On(websockets.EventType_Connect, func(ctx *websockets.Ctx) {
-    err := connections.Set(context.TODO(), ctx.Request.ConnectionID(), map[string]interface{}{
+    err := connections.Set(context.Background(), ctx.Request.ConnectionID(), map[string]interface{}{
       "connectionId": ctx.Request.ConnectionID(),
     })
     if err != nil {
+      fmt.Println("Error storing connection ID in KV store:", err)
       return
     }
   })
 
   ws.On(websockets.EventType_Disconnect, func(ctx *websockets.Ctx) {
-    err := connections.Delete(context.TODO(), ctx.Request.ConnectionID())
+    err := connections.Delete(context.Background(), ctx.Request.ConnectionID())
     if err != nil {
+      fmt.Println("Error deleting connection ID in KV store:", err)
       return
     }
   })
 
   ws.On(websockets.EventType_Message, func(ctx *websockets.Ctx) {
-    connectionStream, err := connections.Keys(context.TODO())
+    connectionStream, err := connections.Keys(context.Background())
     if err != nil {
+      fmt.Println("Error retrieving connection keys from KV store:", err)
       return
     }
 
@@ -222,8 +228,9 @@ func main() {
       }
 
       message := fmt.Sprintf("%s: %s", senderId, ctx.Request.Message())
-      err = ws.Send(context.TODO(), connectionId, []byte(message))
+      err = ws.Send(context.Background(), connectionId, []byte(message))
       if err != nil {
+        fmt.Println("Error sending message to connection ID", connectionId, ":", err)
         return
       }
     }
@@ -239,36 +246,27 @@ Do a quick `go mod tidy` to make sure all new dependencies are resolved.
 
 ## Ok, let's run this thing!
 
-Now that you have your WebSocket application defined with handlers for each event, it's time to test it locally. Update your `nitric.yaml` to point to the service at `websockets/main.go`:
-
-```yaml
-services:
-  - match: websockets/*
-    runtime: go
-    start: go run ./$SERVICE_PATH
-```
+Now that you have your WebSocket application defined with handlers for each event, it's time to test it locally.
 
 ```bash
 nitric start
 ```
 
 Once it starts, the application will be ready to accept WebSocket connections. You can use a WebSocket client like Postman or any other WebSocket tool to test the application. Alternatively, you can use the [Nitric Dashboard](/get-started/foundations/projects/local-development#local-dashboard).
 
-We will keep it running for our tests.
-
 ## Deploy to the cloud
 
-At this point, you can deploy what you've built to any of the supported cloud providers. To do this, start by setting up your credentials and configuration for [AWS](/providers/pulumi/aws).
+At this point, you can deploy what you've built to any of the supported cloud providers. In this example we'll deploy to AWS. Start by setting up your credentials and configuration for the [nitric/aws provider](/providers/pulumi/aws).
 
-Next, we'll need to create a `stack`. A stack represents a deployed instance of an application, which is a key value store of resources defined in your project. You might want separate stacks for each environment, such as stacks for `dev`, `test`, and `prod`. For now, let's start by creating a `dev` stack.
+Next, we'll need to create a `stack file` (deployment target). A stack is a deployed instance of an application. You might want separate stacks for each environment, such as stacks for `dev`, `test`, and `prod`. For now, let's start by creating a file for the `dev` stack.
 
 The `stack new` command below will create a stack named `dev` that uses the `aws` provider.
 
 ```bash
 nitric stack new dev aws
 ```
 
-Continue by checking your stack file `nitric.dev.yaml` and adding in your preferred region. Let's use `us-east-1`.
+Edit the stack file `nitric.dev.yaml` and set your preferred AWS region, for example `us-east-1`.
 
 ### AWS
 
@@ -277,7 +275,7 @@ Continue by checking your stack file `nitric.dev.yaml` and adding in your prefer
   costs associated with deployment.
 </Note>
 
-We called our stack `dev`. Let's try deploying it with the `up` command:
+Let's try deploying the stack with the `up` command:
 
 ```bash
 nitric up

docs/guides/terraform/terratest.mdx

@@ -30,14 +30,14 @@ Our sample project creates a real-time communication service using [WebSockets](
 
 We intend to deploy to AWS and will use Terratest to ensure that the following:
 
-- **API Gateway WebSocket**: Confirm that the websocket endpoint is correctly configured for real-time communication.
+- **WebSocket API**: Confirm that the API Gateway WebSocket API is correctly configured for real-time communication.
 - **DynamoDB Table**: Verify that the key-value store for connections is created and operational.
 - **IAM Roles**: Ensure that permissions for interacting with AWS services are correctly set up.
 
 Let's start by creating a new project for our application.
 
 ```bash
-nitric new my-websocket-app go-starter
+nitric new websocket-app go-starter
 ```
 
 ### Application code
@@ -121,7 +121,7 @@ nitric stack new dev aws-tf
 
 Update this newly created stack file to include your target region:
 
-```yaml
+```yaml title:nitric.dev.yaml
 # The nitric provider to use
 provider: nitric/[email protected]
 
@@ -131,18 +131,18 @@ region: us-east-2
 
 The Nitric Terraform providers are currently in preview, to enable them you'll need to enable beta-providers in your Nitric project. You can do this by adding the following to your project's `nitric.yaml` file:
 
-```
+```yaml title:nitric.yaml
 preview:
   - beta-providers
 ```
 
-Once you've created your Nitric stack, you can generate the Terraform code by running the following command:
+Once you've created your stack file, you can generate the Terraform code by running the following command:
 
 ```
 nitric up
 ```
 
-This will generate the Terraform code for your Nitric application into a folder named `cdktf.out` by default.
+This will generate Terraform code which can deploy your application. The output will be in a folder named `cdktf.out` by default.
 
 ## Add and execute Terratest
 
@@ -170,7 +170,7 @@ touch test/terraform_resources_test.go
 
 Add the following code to `terraform_resources_test.go`:
 
-```go
+```go title:test/terraform_resources_test.go
 package test
 
 import (
@@ -187,7 +187,7 @@ import (
 func TestTerraformResources(t *testing.T) {
 	// Set Terraform options, specifying the directory with your Terraform configuration
 	terraformOptions := &terraform.Options{
-		TerraformDir: "../cdktf.out/stacks/my-websocket-app-dev",
+		TerraformDir: "../cdktf.out/stacks/websocket-app-dev",
 	}
 
 	// Ensure resources are destroyed after test completion
@@ -209,11 +209,11 @@ func TestTerraformResources(t *testing.T) {
 
 	// Test IAM role creation
 	iamClient := iam.New(sess)
-	roleName := "my-websocket-app_websockets-main" // Name of the IAM role to check
+	roleName := "websocket-app_websockets-main" // Name of the IAM role to check
 	_, err = iamClient.GetRole(&iam.GetRoleInput{
 		RoleName: aws.String(roleName),
 	})
-	assert.NoError(t, err, "Expected IAM role 'my-websocket-app_websockets-main' to be created")
+	assert.NoError(t, err, "Expected IAM role 'websocket-app_websockets-main' to be created")
 
 	// Test API gateway webSocket creation
 	apiClient := apigatewayv2.New(sess)