Major refactors and docs updates.

Author: metaskills

README.md

@@ -1,9 +1,7 @@
 
 # Tailscale Lambda Extension for Containers
 
-Inspired by [Corey Quinn](https://github.com/QuinnyPig) Tailscale [layer](https://github.com/QuinnyPig/tailscale-layer) project. This project aims to do the same thing but usable for those working with any Lambda Container runtime language.
-
-This Tailscale extension has been modified from Corey's upstream work. We have removed verbose logging and event lifecycle hooks which just did some verbose logging.
+Inspired by Corey Quinn's [tailscale-layer](https://github.com/QuinnyPig/tailscale-layer) project. This project aims to do the same thing but usable for those working with any Lambda Container runtime language. Our extension has been modified from Corey's upstream work. I have removed verbose logging and event lifecycle hooks. This has reduced startup overhead, duplicate tailscale up calls, and more configuration options.
 
 ## Installation
 
@@ -31,7 +29,7 @@ We publish multi-platform images for both `linux/amd64` and `linux/arm64/v8` and
 - ghcr.io/rails-lambda/tailscale-extension-amzn
 - ghcr.io/rails-lambda/tailscale-extension-debian
 
-## Usage
+## Example Usage
 
 Once your Lambda function starts, you will have a [SOCKS5](https://en.wikipedia.org/wiki/SOCKS) proxy which can communicate with your Tailscale tailnet at `http://localhost:1055`. Here is an example of how to leverage that with Ruby's [socksify](https://github.com/astro/socksify-ruby) gem.
 
@@ -41,85 +39,4 @@ Net::HTTP.socks_proxy('localhost', 1055).start(...) do |http|
 end
 ```
 
-Again, this extension is not coupled to any runtime language. So how you use the SOCKS5 proxy is up to you.
-
-## Why? An Example!
-
-I am currently using this extension to help develop our new LambdaCable gem which uses API Gateway's WebSockets. We reached the point where a faster feedback was required. So I use this proxy to forward all Lambda events to my local development. 
-
-In the example image below, the Tailscale Extension is used on the "Lambda Proxy" to send all HTTP and WebSocket event traffic to my local machine, illustrated below.
-
-```mermaid
-flowchart TB
-  %% Objects
-  usr[/User/]
-  subgraph aws["AWS Environment"]
-    fun(Function URL)
-		api(API Gateway)
-    lam(Lambda Proxy)
-    ddb[(DynamoDB)]:::node-org
-  end
-  subgraph local["Local Environment"]
-    subgraph app["Application"]
-      proxy(Proxy Server)
-    end
-  end
-  %% Flow
-  usr <--> |/*| fun
-  usr <--> |/cable| api
-  fun <--> lam
-  api --> lam
-  lam <--> |Tailscale| proxy
-  app --> api
-  app --> ddb
-  %% Styles
-  classDef node fill:#a99ff0,stroke:#fff,stroke-width:4px,color:#000;
-  classDef node-wht fill:white,stroke:#ccc,stroke-width:1px,color:black;
-  classDef node-org fill:#fdf3ea,stroke:#f7c296,stroke-width:2px,color:#000;
-  classDef desc fill:white,stroke:#ccc,stroke-width:1px,color:black,font-size:12px;
-  classDef node-sml font-size:13px,line-height:2em;
-  classDef fs13 font-size:13px,line-height:1em;
-	linkStyle 4 stroke:#f28add
-	linkStyle 5 stroke:#f28add
-	linkStyle 6 stroke:#f28add
-  class aws node-wht
-  class local node-wht
-```
-
-If you are curious how all this worked with our Lamby gem and our WebSocket demo application, checkout these two pull requests for more details.
-
-- Lamby Gem - [Local Development Proxy Server #164](https://github.com/rails-lambda/lamby/pull/164)
-- WebSocket Demo - [Live Development with Tailscale & Lamby #4
-](https://github.com/rails-lambda/websocket-demo/pull/4)
-
-### Local Proxy Lessons
-
-When running local development services to be used via a proxy, it is important that you use the `0.0.0.0` address to bind to all local interfaces vs the default of `127.0.0.1`. Doing so will ensure that [Tailscale Services](https://tailscale.com/kb/1100/services/) are updated and available. For Rails development server, use something like this:
-
-```shell
-rails s -b 0.0.0.0
-```
-
-[Dev Containers](https://containers.dev/) are an amazing technology spec used by great products such as [Codespaces](https://github.com/features/codespaces) and [VS Code Remote Development](https://code.visualstudio.com/docs/remote/remote-overview). If you are using them, you will need to ensure your Dev Container is forwarding the right ports. If your Dev Container is a single image (vs compose), then you can do this  in the `devcotainer.json` file:
-
-```json
-{
-  "forwardPorts": [3000],
-}
-```
-
-However, our Rails Lambda Dev Container leverages a `dockerComposeFile`, so you would also have to open that compose file and add this to your `devcontainer.json` matching `service` within the compose file. For example:
-
-```yaml
-services:
-  app:
-    ports:
-      - 3000:3000
-```
-
-Here are a few helpful GitHub Issues I found on this topic.
-
-- [Add support for devices in devcontainer-feature.json #153](https://github.com/devcontainers/spec/issues/153)
-- [Port forwarding issue in Containers #1009](https://github.com/microsoft/vscode-remote-release/issues/1009)
-- [Tailscale not detecting Docker Port Forwarding to Host #5813](https://github.com/tailscale/tailscale/issues/5813)
-
+Again, this extension is not coupled to any runtime language. So how you use the SOCKS5 proxy is up to you. Enjoy!

src/tailscale.sh

@@ -5,60 +5,52 @@
 set -euo pipefail
 set +x
 
+# Configuration
 OWN_FILENAME="$(basename "$0")"
 LAMBDA_EXTENSION_NAME="$OWN_FILENAME" # (external) extension name has to match the filename
 TMPFILE="/tmp/tailscale.data"
 
-# Graceful Shutdown
-_term() {
-  echo "[${LAMBDA_EXTENSION_NAME}] Received SIGTERM"
-  # forward SIGTERM to child procs and exit
-  kill -TERM "$PID" 2>/dev/null
-  echo "[${LAMBDA_EXTENSION_NAME}] Exiting"
-  exit 0
-}
-
-forward_sigterm_and_wait() {
-  trap _term SIGTERM
-  wait "$PID"
-  trap - SIGTERM
-}
-
 # Registration
 HEADERS="$(mktemp)"
 echo "[${LAMBDA_EXTENSION_NAME}] Registering at http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register"
-curl -sS -LD "$HEADERS" -XPOST "http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register" --header "Lambda-Extension-Name: ${LAMBDA_EXTENSION_NAME}" -d "{ \"events\": [\"SHUTDOWN\", \"INVOKE\"]}" > $TMPFILE
+curl -sS -LD "$HEADERS" -XPOST "http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register" --header "Lambda-Extension-Name: ${LAMBDA_EXTENSION_NAME}" -d "{ \"events\": [\"SHUTDOWN\"]}" > $TMPFILE
 
-RESPONSE=$(<$TMPFILE)
 # Extract Extension ID from response headers
+RESPONSE=$(<$TMPFILE)
 EXTENSION_ID=$(grep -Fi Lambda-Extension-Identifier "$HEADERS" | tr -d '[:space:]' | cut -d: -f2)
 echo "[${LAMBDA_EXTENSION_NAME}] Registration response: ${RESPONSE} with EXTENSION_ID $(grep -Fi Lambda-Extension-Identifier "$HEADERS" | tr -d '[:space:]' | cut -d: -f2)"
 
 # Start the Tailscale process
+echo "[${LAMBDA_EXTENSION_NAME}] Tailscale process..." 1>&2;
+/opt/bin/tailscaled --tun=userspace-networking --socks5-server=localhost:1055 --socket=/tmp/tailscale.sock --state=/tmp/tailscale &
+TAILSCALED_PID=$!
+echo "[${LAMBDA_EXTENSION_NAME}] TAILSCALED_PID: ${TAILSCALED_PID}" 1>&2;
+sleep 1
+
+# Tailscale up
+echo "[${LAMBDA_EXTENSION_NAME}] Tailscale up..." 1>&2;
 TS_HOSTNAME=${TS_HOSTNAME:-lambda}
-if [ -n "${AWS_LAMBDA_FUNCTION_VERSION:-}" ]; then
+if [ "${AWS_LAMBDA_FUNCTION_VERSION}" != '$LATEST' ]; then
   TS_HOSTNAME="${TS_HOSTNAME}-v${AWS_LAMBDA_FUNCTION_VERSION}"
 fi
-/opt/bin/tailscaled --tun=userspace-networking --socks5-server=localhost:1055 --socket=/tmp/tailscale.sock --state=/tmp/tailscale & sleep 2
 until /opt/bin/tailscale --socket=/tmp/tailscale.sock up --authkey="${TS_KEY}" --hostname="${TS_HOSTNAME}"
 do
   sleep 0.1
 done
+sleep 1
 
-# Event processing
+# Waiting for SHUTDOWN event.
 while true
 do
   echo "[${LAMBDA_EXTENSION_NAME}] Waiting for event. Get /next event from http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/event/next"
   # Get an event. The HTTP request will block until one is received
-  curl -sS -L -XGET "http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/event/next" --header "Lambda-Extension-Identifier: ${EXTENSION_ID}" > $TMPFILE &
-  PID=$!
-  forward_sigterm_and_wait
+  curl -sS -L -XGET "http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/event/next" --header "Lambda-Extension-Identifier: ${EXTENSION_ID}" > $TMPFILE
+  echo "[${LAMBDA_EXTENSION_NAME}] Event received. Processing..."  1>&2;
   EVENT_DATA=$(<$TMPFILE)
-  if [[ $EVENT_DATA == *"SHUTDOWN"* ]]; then
-    echo "[extension: ${LAMBDA_EXTENSION_NAME}] Received SHUTDOWN event. Exiting."  1>&2;
-    # Cleanly shut down the Tailscale process
-    /opt/bin/tailscale --socket=/tmp/tailscale.sock down
-    exit 0 # Exit if we receive a SHUTDOWN event
-  fi
-  sleep 1
+  cat $EVENT_DATA 1>&2;
+  echo "[${LAMBDA_EXTENSION_NAME}] Calling tailscale down..."  1>&2;
+  /opt/bin/tailscale --socket=/tmp/tailscale.sock down
+  echo "[${LAMBDA_EXTENSION_NAME}] Sending term to ${TAILSCALED_PID}..."  1>&2;
+  kill -TERM "$TAILSCALED_PID" 2>/dev/null
+  exit 0
 done