diff --git a/code-samples/serving/websockets-go/Dockerfile b/code-samples/serving/websockets-go/Dockerfile new file mode 100644 index 0000000000..e2ae091ba8 --- /dev/null +++ b/code-samples/serving/websockets-go/Dockerfile @@ -0,0 +1,34 @@ +# Use the official Golang image to create a build artifact. +# This is based on Debian and sets the GOPATH to /go. +FROM golang:latest as builder + +ARG TARGETOS +ARG TARGETARCH + +# Create and change to the app directory. +WORKDIR /app + +# Initialize the Go module inside the Dockerfile. +RUN go mod init mymodule + +# Copy local code to the container image. +COPY . ./ + +# Install dependencies and tidy up the go.mod and go.sum files. +RUN go mod tidy + +# Build the binary. +# -mod=readonly ensures immutable go.mod and go.sum in container builds. +RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -mod=readonly -v -o server ./cmd/server + +# Use the official Alpine image for a lean production container. +# https://hub.docker.com/_/alpine +# https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds +FROM alpine:3 +RUN apk add --no-cache ca-certificates + +# Copy the binary to the production image from the builder stage. +COPY --from=builder /app/server /server + +# Run the web service on container startup. +CMD ["/server"] diff --git a/code-samples/serving/websockets-go/README.md b/code-samples/serving/websockets-go/README.md new file mode 100644 index 0000000000..723be3383c --- /dev/null +++ b/code-samples/serving/websockets-go/README.md @@ -0,0 +1,138 @@ +# WebSocket - Go + +A simple [WebSocket](https://datatracker.ietf.org/doc/html/rfc6455) server that performs the HTTP upgrade and prints log messages on all standardized WebSocket events, such as `open`, `message`, `close` and `error`. The server is written in Golang and uses the [Gorilla WebSocket](github.com/gorilla/websocket) library. + + +## Before you begin + +- A Kubernetes cluster with Knative installed and DNS configured. See + [Install Knative Serving](https://knative.dev/docs/install/serving/install-serving-with-yaml). +- [ko](https://github.com/ko-build/ko) or [Docker](https://www.docker.com) installed and running on your local machine, + and a Docker Hub account configured (we'll use it for a container registry). + +## The sample code. + +1. If you look in `cmd/server/main.go`, you will the `main` function setting a `handleWebSocket` function and starting the web server on the `/ws` context: + + ```go + func main() { + http.HandleFunc("/ws", handleWebSocket) + fmt.Println("Starting server on :8080...") + if err := http.ListenAndServe(":8080", nil); err != nil { + log.Fatalf("Server error: %v", err) + } + } + ``` + +2. The `handleWebSocket` performs the protocol upgrade and assigns various websocket handler functions, such as `OnOpen` or `OnMessage`: + + ```go + func handleWebSocket(w http.ResponseWriter, r *http.Request) { + conn, err := upgrader.Upgrade(w, r, nil) + if err != nil { + log.Printf("Error upgrading to websocket: %v", err) + return + } + handlers.OnOpen(conn) + + go func() { + defer handlers.OnClose(conn) + for { + messageType, message, err := conn.ReadMessage() + if err != nil { + handlers.OnError(conn, err) + break + } + handlers.OnMessage(conn, messageType, message) + } + }() + } + ``` + +3. The WebSocket application logic is located in the `pkg/handlers/handlers.go` file and contains callbacks for each WebSocket event: + + ```go + func OnOpen(conn *websocket.Conn) { + log.Printf("WebSocket connection opened: %v", conn.RemoteAddr()) + } + + func OnMessage(conn *websocket.Conn, messageType int, message []byte) { + log.Printf("Received message from %v: %s", conn.RemoteAddr(), string(message)) + + if err := conn.WriteMessage(messageType, message); err != nil { + log.Printf("Error sending message: %v", err) + } + } + + func OnClose(conn *websocket.Conn) { + log.Printf("WebSocket connection closed: %v", conn.RemoteAddr()) + conn.Close() + } + + func OnError(conn *websocket.Conn, err error) { + log.Printf("WebSocket error from %v: %v", conn.RemoteAddr(), err) + } + ``` + +## Build the application + + ### Dockerfile + + * If you look in `Dockerfile`, you will see a method for pulling in the dependencies and building a small Go container based on Alpine. You can build and push this to your registry of choice via: +```bash +# Build and push the container on your local machine. +docker buildx build --platform linux/arm64,linux/amd64 -t "" --push . +``` + + ### ko + + * You can use `ko` to build and push just the image with: +```bash +ko publish github.com/knative/docs/code-samples/serving/websockets-go +``` + However, if you use `ko` for the next step, this is not necessary. + +## Deploy the application + + ### yaml (with Dockerfile) + * If you look in `service.yaml`, take the `` name you used earlier and insert it into the `image:` field, then run: +```bash +kubectl apply -f config/service.yaml +``` + + ### yaml (with ko) + * If using `ko` to build and push: +```bash +ko apply -f config/service.yaml +``` + +## Testing the WebSocket server + +Get the URL for your Service with: + + ```bash + kubectl get ksvc + NAME URL LATESTCREATED LATESTREADY READY REASON + websocket-server http://websocket-server.default.svc.cluster.local websocket-server-00001 websocket-server-00001 True + ``` + +Now run a container with the [wscat](https://github.com/websockets/wscat) CLI and point it to the WebSocket application `ws://websocket-server.default.svc.cluster.local/ws`, like: + + + ```bash + kubectl run --rm -i --tty wscat --image=monotykamary/wscat --restart=Never -- -c ws://websocket-server.default.svc.cluster.local/ws + ``` + +Afterward you can chat with the WebSocket server like: + + ```bash + ```If you don't see a command prompt, try pressing enter. + ```connected (press CTRL+C to quit) + ```> Hello + ```< Hello + ```> + ``` + +The above is scaling to exactly one pod, since only one client was connected. Since Knative Serving allows you a dynamic scalling, a certain number of concurrent connections lead to a number of pods. + +>> **NOTE:** Depending on the target annotation you have ([`autoscaling.knative.dev/target`](https://knative.dev/docs/serving/autoscaling/autoscaling-targets/)) you can scale based on num of connections. diff --git a/code-samples/serving/websockets-go/cmd/server/main.go b/code-samples/serving/websockets-go/cmd/server/main.go new file mode 100644 index 0000000000..2859aa6358 --- /dev/null +++ b/code-samples/serving/websockets-go/cmd/server/main.go @@ -0,0 +1,45 @@ +package main + +import ( + "fmt" + "log" + "net/http" + + "github.com/gorilla/websocket" + "github.com/knative/docs/code-samples/serving/websockets-go/pkg/handlers" +) + +var upgrader = websocket.Upgrader{ + ReadBufferSize: 1024, + WriteBufferSize: 1024, + CheckOrigin: func(r *http.Request) bool { return true }, +} + +func handleWebSocket(w http.ResponseWriter, r *http.Request) { + conn, err := upgrader.Upgrade(w, r, nil) + if err != nil { + log.Printf("Error upgrading to websocket: %v", err) + return + } + handlers.OnOpen(conn) + + go func() { + defer handlers.OnClose(conn) + for { + messageType, message, err := conn.ReadMessage() + if err != nil { + handlers.OnError(conn, err) + break + } + handlers.OnMessage(conn, messageType, message) + } + }() +} + +func main() { + http.HandleFunc("/ws", handleWebSocket) + fmt.Println("Starting server on :8080...") + if err := http.ListenAndServe(":8080", nil); err != nil { + log.Fatalf("Server error: %v", err) + } +} diff --git a/code-samples/serving/websockets-go/config/service.yaml b/code-samples/serving/websockets-go/config/service.yaml new file mode 100644 index 0000000000..27a6deb505 --- /dev/null +++ b/code-samples/serving/websockets-go/config/service.yaml @@ -0,0 +1,10 @@ +apiVersion: serving.knative.dev/v1 +kind: Service +metadata: + name: websockets-go + namespace: default +spec: + template: + spec: + containers: + - image: ko://github.com/knative/docs/code-samples/serving/websockets-go/cmd/server diff --git a/code-samples/serving/websockets-go/go.mod b/code-samples/serving/websockets-go/go.mod new file mode 100644 index 0000000000..d8b204a5bf --- /dev/null +++ b/code-samples/serving/websockets-go/go.mod @@ -0,0 +1,5 @@ +module github.com/knative/docs/code-samples/serving/websockets-go + +go 1.22 + +require github.com/gorilla/websocket v1.5.0 diff --git a/code-samples/serving/websockets-go/go.sum b/code-samples/serving/websockets-go/go.sum new file mode 100644 index 0000000000..e5a03d4dc9 --- /dev/null +++ b/code-samples/serving/websockets-go/go.sum @@ -0,0 +1,2 @@ +github.com/gorilla/websocket v1.5.0 h1:PPwGk2jz7EePpoHN/+ClbZu8SPxiqlu12wZP/3sWmnc= +github.com/gorilla/websocket v1.5.0/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE= diff --git a/code-samples/serving/websockets-go/pkg/handlers/handlers.go b/code-samples/serving/websockets-go/pkg/handlers/handlers.go new file mode 100644 index 0000000000..dd10819a2d --- /dev/null +++ b/code-samples/serving/websockets-go/pkg/handlers/handlers.go @@ -0,0 +1,28 @@ +package handlers + +import ( + "log" + + "github.com/gorilla/websocket" +) + +func OnOpen(conn *websocket.Conn) { + log.Printf("WebSocket connection opened: %v", conn.RemoteAddr()) +} + +func OnMessage(conn *websocket.Conn, messageType int, message []byte) { + log.Printf("Received message from %v: %s", conn.RemoteAddr(), string(message)) + + if err := conn.WriteMessage(messageType, message); err != nil { + log.Printf("Error sending message: %v", err) + } +} + +func OnClose(conn *websocket.Conn) { + log.Printf("WebSocket connection closed: %v", conn.RemoteAddr()) + conn.Close() +} + +func OnError(conn *websocket.Conn, err error) { + log.Printf("WebSocket error from %v: %v", conn.RemoteAddr(), err) +} diff --git a/docs/samples/serving.md b/docs/samples/serving.md index 3773a95da7..8ec7932cea 100644 --- a/docs/samples/serving.md +++ b/docs/samples/serving.md @@ -19,3 +19,4 @@ See [all Knative code samples](https://github.com/knative/docs/tree/main/code-sa | Kong Routing | An example of mapping multiple Knative services to different paths under a single domain name using the Kong API gateway. | [Go](https://github.com/knative/docs/tree/main/code-samples/serving/kong-routing-go) | | Knative Secrets | A simple app that demonstrates how to use a Kubernetes secret as a Volume in Knative. | [Go](https://github.com/knative/docs/tree/main/code-samples/serving/secrets-go) | | Multi Container | A quick introduction that highlights how to build and deploy an app using Knative Serving for multiple containers. | [Go](https://github.com/knative/docs/tree/main/code-samples/serving/multi-container) | +| WebSocket Server | A simple WebSocket server. | [Go](https://github.com/knative/docs/tree/main/code-samples/serving/websocket-go) |