docs: readme

Author: rehanvdm

README.md

@@ -1,49 +1,50 @@
 # Tailscale Lambda Extension Proxy
 
-[![npm version](https://badge.fury.io/js/tailscale-lambda-proxy.svg)](https://badge.fury.io/js/tailscale-lambda-proxy)
+[![npm version](https://badge.fury.io/js/tailscale-lambda-proxy.svg)](https://badge.fury.io/js/tailscale-lambda-proxy)  
 [![PyPI version](https://badge.fury.io/py/tailscale-lambda-proxy.svg)](https://badge.fury.io/py/tailscale-lambda-proxy)
 
-A CDK construct that creates an AWS Lambda Function that acts as a proxy to your Tailscale network.
+A CDK construct that creates an AWS Lambda Function acting as a transparent proxy to your Tailscale network.
 
-Available in CDK as a TypeScript NPM Package and Python PyPi Package:
+Available as both a TypeScript NPM Package and a Python PyPi Package:
 - [TypeScript NPM Package](https://www.npmjs.com/package/tailscale-lambda-proxy)
 - [Python PyPi Package](https://pypi.org/project/tailscale-lambda-proxy/)
 
-## Why use a proxy? 
+## Why use a proxy?
 
-The Proxy Lambda uses the [Tailscale Lambda Extension](https://github.com/rehanvdm/tailscale-lambda-extension) CDK 
-construct. 
+The Proxy Lambda leverages the [Tailscale Lambda Extension](https://github.com/rehanvdm/tailscale-lambda-extension) CDK
+construct.
 
 It is recommended to use the Proxy Lambda to simplify connecting to your Tailscale network and reduces cold starts
 by reusing the same Lambda function for all your Tailscale connected traffic.
 
 Use the extension directly if:
-- You only have **a single Lambda**/service that needs to connect to your Tailscale network.
-- You are okay with accepting that this Lambda will have mixed responsibilities (i.e. connecting to Tailscale and your 
-  business logic).
-
-Use the Proxy Lambda (recommended) construct if:
-- You have **multiple Lambdas**/services that need to connect to your Tailscale network. The proxy Lambda will 
-  effectively create a "pool" of warm connections to your Tailscale network, ready to be used by any other Lambda 
-  that calls it.
-- You want to separate concerns and have a dedicated Lambda function that only connects to your Tailscale network.
-- Authentication to your Tailscale network (through the proxy) is then moved to an IAM level. Access is granted to
-  the Proxy Lambda Function URL (FURL), and not to the Tailscale API Secret Manager directly.
+- You have **a single Lambda** or service that needs to connect to your Tailscale network.
+- You are comfortable with this Lambda having mixed responsibilities, such as connecting to Tailscale and running
+  business logic.
+
+Use the Proxy Lambda (recommended) if:
+- You have **multiple Lambdas** or services requiring connection to your Tailscale network. The Proxy Lambda *eventually*
+  creates a "pool of warm connections" to the Tailscale network, ready for use by other Lambdas.
+- You want to separate responsibilities by having a dedicated Lambda for Tailscale connectivity.
+- Authentication to the Tailscale network is handled at the IAM level, where access is granted to the Proxy Lambda's
+  Function URL (FURL), instead of directly to the Tailscale API Secret Manager.
 
 ## Usage
 
 > [!TIP]  
-> See the complete example in the [tailscale-lambda-proxy-example](https://github.com/rehanvdm/tailscale-lambda-proxy-example)
-> repository.
+> Refer to the [tailscale-lambda-proxy-example](https://github.com/rehanvdm/tailscale-lambda-proxy-example) repository
+> for a complete example.
+
+### Installation
 
-Install the package:
+Install the package:  
 ```bash
 npm install tailscale-lambda-proxy
 ```
 
-The Lambda Proxy requires the following:
-- `tsSecretApiKey` - The AWS Secrets Manager secret that contains the pure text Tailscale API Key.
-- `tsHostname` - The "Machine" name as shown in the Tailscale admin console that identifies this Lambda(s) function.
+The Proxy Lambda requires the following:
+- `tsSecretApiKey`: The AWS Secrets Manager secret containing the Tailscale API Key as plain text.
+- `tsHostname`: The "Machine" name as shown in the Tailscale admin console, which identifies the Lambda function(s).
 
 ```typescript
 import * as cdk from 'aws-cdk-lib';
@@ -90,70 +91,101 @@ export class MyStack extends cdk.Stack {
 
 ## Accessing your Tailscale Network through the Proxy
 
-The code below can be found in the
-[tailscale-lambda-proxy-example](https://github.com/rehanvdm/tailscale-lambda-proxy-example) repository.
+The [tailscale-lambda-proxy-example](https://github.com/rehanvdm/tailscale-lambda-proxy-example) repository contains
+the following example.
 
-**The Tailscale Lambda Proxy is transparent**. It does not modify the request or response that is sent to the machine in 
-any way. It simply forwards the request (path, method, headers, and body) to the machine and returns the response.
+The Tailscale Lambda Proxy is fully transparent. It forwards requests (path, method, headers, and body) to the machine
+and returns the response without modification.
 
-There are 2 important components when interacting with the Tailscale Lambda Proxy:
+Key considerations when using the Proxy:
 1. All requests must be signed with the IAM Signature V4 algorithm.
-2. The IP address and port of your Tailscale connected machine/device should be placed in the 
-   headers when making the call to the proxy.
-
-### Signing Requests
+2. The target machine's IP address and port must be included in the headers when making requests to the Proxy.
 
-The Lambda Proxy exposes a Function URL secured with IAM Authentication. The caller Lambda only needs this URL and IAM
-permissions to call it. Then it needs to sign all requests with the IAM Signature V4 algorithm. For Typescript users, 
-you can use the [aws4](https://www.npmjs.com/package/aws4) package to sign requests.
+#### Signing Requests
 
-### Including the correct headers
+The Proxy Lambda exposes a Function URL secured with IAM Authentication. The caller Lambda requires this URL and
+IAM permissions to make requests. These requests must be signed with the IAM Signature V4 algorithm. For TypeScript,
+use the [aws4](https://www.npmjs.com/package/aws4) package to sign requests.
 
-When making a request to the Proxy, you need to include the IP address and port of the Tailscale connected machine/device
-that you are targeting in the headers.
+#### Including Target Headers
 
-The `ts-` headers below will be removed before forwarding the request to the Tailscale machine/device, they are only 
-used for routing and internal logic to the proxy. 
+When calling the Proxy, include the following headers to specify the target machine:
+- `ts-target-ip`: The IP address of the Tailscale-connected machine/device.
+- `ts-target-port`: The port of the Tailscale-connected machine/device.
 
-- `ts-target-ip` - The IP address of the Tailscale connected machine/device.
-- `ts-target-port` - The port of the Tailscale connected machine/device.
+These `ts-` headers are removed before the request is forwarded to the target machine.
 
-### Create CloudWatch Tracking Metrics
+### Creating CloudWatch Tracking Metrics
 
-These metrics are optional and are used to track the success and failure of requests made through the proxy.
- 
-To enable the optional tracking metrics, you can include the following headers as well:
-- `ts-metric-service` - The name of the service or API making the request.
-- `ts-metric-dimension-name` - The name of the dimension to track (e.g., client name).
-- `ts-metric-dimension-value` - The value associated with the dimension.
+To enable optional tracking metrics, add the following headers to your request:
+- `ts-metric-service`: The name of the service or API making the request.
+- `ts-metric-dimension-name`: The dimension name for tracking (such as client name).
+- `ts-metric-dimension-value`: The value associated with the dimension.
 
-For each request, one of the following CloudWatch metrics is created:
-- `success`: Recorded when the request is successfully delivered to the target server. Note that this does not depend on
-  the HTTP status code of the API response.
-- `failure`: Recorded when the request fails to reach the target server. Possible reasons include network issues or the
-  target server being unavailable.
+Metrics generated in CloudWatch:
+- `success`: Logged when a request reaches the target server, regardless of the API response status.
+- `failure`: Logged when a request fails to reach the target server, typically due to network issues or server
+  unavailability.
 
-Here is an example of headers for a request:
-- `ts-metric-service`: `gallagher` the name of the calling service or API being targeted.
-- `ts-metric-dimension-name`: `client` tracks the client name to be used for monitoring or alerts.
-- `ts-metric-dimension-value`: `rehan-test-client` the specific client name.
+Example headers for a request:
+- `ts-metric-service`: `gallagher`, indicating the service or API making the request.
+- `ts-metric-dimension-name`: `client`, used for monitoring or alerts.
+- `ts-metric-dimension-value`: `rehan-test-client`, identifying the specific client.
 
-This setup generates a CloudWatch metric similar to the one below:  
+This configuration generates CloudWatch metrics similar to the screenshot below:  
 ![tailscale-cloudwatch-metric.png](_imgs/tailscale-cloudwatch-metric.png)
 
 ### Error Handling
 
-In efforts to keep the Proxy Lambda transparent, all traffic, including errors are passed back to the caller. This makes
-it difficult to determine if the error was due to the Proxy Lambda or if it originated from the Tailscale connected
-machine/device. 
+To maintain transparency, the Proxy Lambda passes all traffic, including errors, back to the caller. This approach
+makes it difficult to determine whether an error originated from the Proxy Lambda or the Tailscale-connected machine.
+
+A Proxy Lambda error can be identified by the following headers in the response:
+- `ts-error-name`: The error name.
+- `ts-error-message`: The error message.
+
+### Code Examples
+
+Refer to the [tailscale-lambda-proxy-example](https://github.com/rehanvdm/tailscale-lambda-proxy-example) repository
+for the complete example. The partial snippet below shows a Lambda function accessing an express server running
+on a Tailscale-connected machine. The [TailscaleProxyApi](https://github.com/rehanvdm/tailscale-lambda-proxy-example/blob/f5e95c9b2294bd185bbe5b372a24dafcafc17297/lib/lambda/tailscale-caller/tailscale-proxy-api.ts) 
+class implements the above-mentioned usage specifications.
+
+```typescript
+import {TailscaleProxyApi} from "./tailscale-proxy-api";
+
+export const handler = async (event: any) => {
+  console.log(JSON.stringify(event, null, 2));
 
-A Lambda Proxy error can be identified by the presence of the following response headers:
-- `ts-error-name` - The name of the error.
-- `ts-error-message` - The error message.
+  // Connect to the tailscale network with your laptop, get your tailscale IP, then start the express server in
+  // `express-local-api` with `npm run start` and then run the lambda function to test the connection.
+  const targetIp = "100.91.164.93";
+  const targetPort = 3000;
+
+  const api = new TailscaleProxyApi(process.env.TS_PROXY_URL!, process.env.AWS_REGION!,
+    targetIp, targetPort,
+    "express-local-api", "client", "client-a"
+    );
+
+  const resp = await api.request("/ping", "GET");
+
+  if(resp.proxyError) {
+    throw new Error(`PROXY ERROR: ${resp.proxyError}`);
+  }
+  else if(resp.response.statusCode !== 200) {
+    throw new Error(`API ERROR: ${resp.response.statusCode} with body: ${resp.response.body}`);
+  }
+
+  console.log('');
+  console.log('API SUCCESS: ', resp.response.body);
+
+  return true;
+};
+```
 
 ## Additional Information
 
-See the [Tailscale Lambda Extension](https://github.com/rehanvdm/tailscale-lambda-extension) for more information on:
-- How to configure Tailscale
-- Limitations like cold start times, package sizes and the lack of DNS resolution.
-- Implementation Details
+Refer to the [Tailscale Lambda Extension](https://github.com/rehanvdm/tailscale-lambda-extension) documentation for:
+- Configuring Tailscale.
+- Understanding limitations such as cold start times, package sizes, and the lack of DNS resolution.
+- Additional implementation details.