Rename new readme

README-UPDATED.md

@@ -1,145 +0,0 @@
-# Serverless Redis HTTP (SRH)
-
-A Redis proxy and connection pooler that uses HTTP rather than the Redis binary protocol.\
-The aim of this project is to be entirely compatible with Upstash, and work with any Upstash supported Redis version.
-
-Use cases for SRH:
-- For usage in your CI pipelines, creating Upstash databases is tedious, or you have lots of parallel runs.
-    - See [Using in GitHub Actions](#in-github-actions) on how to quickly get SRH setup for this context.
-- For usage inside of Kubernetes, or any network whereby the Redis server is not exposed to the internet.
-    - See [Using in Docker Compose](#via-docker-compose) for the various setup options directly using the Docker Container.
-- For local development environments, where you have a local Redis server running, or require offline access.
-    - See [Using the Docker Command](#via-docker-command), or [Using Docker Compose](#via-docker-compose).
-
-## Differences between Upstash and Redis to note
-SRH tests are ran nightly against the `@upstash/redis` JavaScript package. However, there are some minor differences between Upstash's implementation of Redis and the official Redis code.
-
-- The `UNLINK` command will not throw an error when 0 keys are given to it. In Redis, and as such SRH, an error will be thrown.
-- In the `ZRANGE` command, in Upstash you are not required to provide `BYSCORE` or `BYLEX` in order to use the `LIMIT` argument. With Redis/SRH, this will throw an error if not provided.
-- The Upstash implementation of `RedisJSON` contains a number of subtle differences in what is returned in responses. For this reason, **it is not advisable to use SRH with Redis Stack if you are testing your Upstash implementation that uses JSON commands**. If you don't use any JSON commands, then all is good :)
-- **SRH does not implement commands via paths, or accepting the token via a query param**. Only the body method is implemented, which the `@upstash/redis` SDK uses.
-
-### Similarities to note:
-
-Pipelines and Transaction endpoints are also implemented, also using the body data only. You can read more about the RestAPI here: [Upstash Docs on the Rest API](https://docs.upstash.com/redis/features/restapi)
-
-Response encoding is also fully implemented. This is enabled by default by the `@upstash/redis` SDK. You can read more about that here: [Upstash Docs on Hashed Responses](https://docs.upstash.com/redis/sdks/javascriptsdk/troubleshooting#hashed-response)
-
-## How to use with the `@upstash/redis` SDK
-Simply set the REST URL and token to where the SRH instance is running. For example:
-```ts
-import {Redis} from '@upstash/redis';
-
-export const redis = new Redis({
-    url: "http://localhost:8079",
-    token: "example_token",
-});
-```
-
-# Setting up SRH
-## Via Docker command
-If you have a locally running Redis server, you can simply start an SRH container that connects to it.
-In this example, SRH will be running on port `8080`.
-
-```bash
-docker run \
-    -it -d -p 8080:80 --name srh \
-    -e SRH_MODE=env \
-    -e SRH_TOKEN=your_token_here \
-    -e SRH_CONNECTION_STRING="redis://your_server_here:6379" \
-    hiett/serverless-redis-http:latest
-```
-
-## Via Docker Compose
-If you wish to run in Kubernetes, this should contain all the basics would need to set that up. However, be sure to read the Configuration Options, because you can create a setup whereby multiple Redis servers are proxied.
-```yml
-version: '3'
-services:
-  redis:
-    image: redis
-    ports:
-      - '6379:6379'
-  serverless-redis-http:
-    ports:
-      - '8079:80'
-    image: hiett/serverless-redis-http:latest
-    environment:
-      SRH_MODE: env
-      SRH_TOKEN: example_token
-      SRH_CONNECTION_STRING: 'redis://redis:6379' # Using `redis` hostname since they're in the same Docker network.
-```
-
-## In GitHub Actions
-
-SRH works nicely in GitHub Actions because you can run it as a container in a job's services. Simply start a Redis server, and then
-SRH alongside it. You don't need to worry about a race condition of the Redis instance not being ready, because SRH doesn't create a Redis connection until the first command comes in.
-
-```yml
-name: Test @upstash/redis compatability
-on:
-  push:
-  workflow_dispatch:
-
-env:
-  SRH_TOKEN: example_token
-
-jobs:
-  container-job:
-    runs-on: ubuntu-latest
-    container: denoland/deno
-    services:
-      redis:
-        image: redis/redis-stack-server:6.2.6-v6 # 6.2 is the Upstash compatible Redis version
-      srh:
-        image: hiett/serverless-redis-http:latest
-        env:
-          SRH_MODE: env # We are using env mode because we are only connecting to one server.
-          SRH_TOKEN: ${{ env.SRH_TOKEN }}
-          SRH_CONNECTION_STRING: redis://redis:6379
-
-    steps:
-      # You can place your normal testing steps here. In this example, we are running SRH against the upstash/upstash-redis test suite.
-      - name: Checkout code
-        uses: actions/checkout@v3
-        with:
-          repository: upstash/upstash-redis
-
-      - name: Run @upstash/redis Test Suite
-        run: deno test -A ./pkg
-        env:
-          UPSTASH_REDIS_REST_URL: http://srh:80
-          UPSTASH_REDIS_REST_TOKEN: ${{ env.SRH_TOKEN }}
-```
-
-# Configuration Options
-
-SRH works with multiple Redis servers, and can pool however many connections you wish it to. It will shut down un-used pools after 15 minutes of inactivity. Upon the next command, it will re-build the pool.
-
-## Connecting to multiple Redis servers at the same time
-
-The examples above use environment variables in order to tell SRH which Redis server to connect to. However, you can also use a configuration JSON file, which lets you create as many connections as you wish. The token provided in each request will decide which pool is used.
-
-Create a JSON file, in this example called `tokens.json`:
-```json
-{
-    "example_token": {
-        "srh_id": "some_unique_identifier",
-        "connection_string": "redis://localhost:6379",
-        "max_connections": 3
-    }
-}
-```
-You can provide as many entries to the base object as you wish, and configure the number of max connections per pool. The `srh_id` is used internally to keep track of instances. It can be anything you want.
-
-Once you have created this, mount it to the docker container to the `/app/srh-config/tokens.json` file. Here is an example docker command:
-
-`docker run -it -d -p 8079:80 --name srh --mount type=bind,source=$(pwd)/tokens.json,target=/app/srh-config/tokens.json hiett/serverless-redis-http:latest`
-
-## Environment Variables
-
-| Name | Default Value | Notes |
-| ---- | ------------- | ----- |
-| SRH_MODE | `file` | Can be `env` or `file`. If `file`, see [Connecting to multiple Redis servers](#connecting-to-multiple-redis-servers-at-the-same-time). If set to `env`, you are required to provide the following environment variables: |
-| SRH_TOKEN | `<required if SRH_MODE = env>` | Set the token that the Rest API will require |
-| SRH_CONNECTION_STRING | `<required if SRH_MODE = env>` | Sets the connection string to the Redis server. |
-| SRH_MAX_CONNECTIONS | `3` | Only used if `SRH_MODE=env`.

README.md

@@ -1,25 +1,33 @@
-# SRH: Serverless Redis HTTP
+# Serverless Redis HTTP (SRH)
 
----
+A Redis proxy and connection pooler that uses HTTP rather than the Redis binary protocol.\
+The aim of this project is to be entirely compatible with Upstash, and work with any Upstash supported Redis version.
 
-**TLDR: If you want to run a local Upstash-compatible HTTP layer in front of your Redis:**
+Use cases for SRH:
+- For usage in your CI pipelines, creating Upstash databases is tedious, or you have lots of parallel runs.
+    - See [Using in GitHub Actions](#in-github-actions) on how to quickly get SRH setup for this context.
+- For usage inside of Kubernetes, or any network whereby the Redis server is not exposed to the internet.
+    - See [Using in Docker Compose](#via-docker-compose) for the various setup options directly using the Docker Container.
+- For local development environments, where you have a local Redis server running, or require offline access.
+    - See [Using the Docker Command](#via-docker-command), or [Using Docker Compose](#via-docker-compose).
 
-0) Have a locally running Redis instance - in this example bound to the default port 6379
-1) create a json file called tokens.json in a folder called srh-config (`srh-config/tokens.json`)
-2) paste this in:
-  ```json
-{
-    "example_token": {
-        "srh_id": "some_unique_identifier",
-        "connection_string": "redis://localhost:6379",
-        "max_connections": 3
-    } 
-}
-  ```
-3) Run this command:
-`docker run -it -d -p 8079:80 --name srh --mount type=bind,source=$(pwd)/srh-config/tokens.json,target=/app/srh-config/tokens.json hiett/serverless-redis-http:latest`
-4) Set this as your Upstash configuration
-```js
+## Differences between Upstash and Redis to note
+SRH tests are ran nightly against the `@upstash/redis` JavaScript package. However, there are some minor differences between Upstash's implementation of Redis and the official Redis code.
+
+- The `UNLINK` command will not throw an error when 0 keys are given to it. In Redis, and as such SRH, an error will be thrown.
+- In the `ZRANGE` command, in Upstash you are not required to provide `BYSCORE` or `BYLEX` in order to use the `LIMIT` argument. With Redis/SRH, this will throw an error if not provided.
+- The Upstash implementation of `RedisJSON` contains a number of subtle differences in what is returned in responses. For this reason, **it is not advisable to use SRH with Redis Stack if you are testing your Upstash implementation that uses JSON commands**. If you don't use any JSON commands, then all is good :)
+- **SRH does not implement commands via paths, or accepting the token via a query param**. Only the body method is implemented, which the `@upstash/redis` SDK uses.
+
+### Similarities to note:
+
+Pipelines and Transaction endpoints are also implemented, also using the body data only. You can read more about the RestAPI here: [Upstash Docs on the Rest API](https://docs.upstash.com/redis/features/restapi)
+
+Response encoding is also fully implemented. This is enabled by default by the `@upstash/redis` SDK. You can read more about that here: [Upstash Docs on Hashed Responses](https://docs.upstash.com/redis/sdks/javascriptsdk/troubleshooting#hashed-response)
+
+## How to use with the `@upstash/redis` SDK
+Simply set the REST URL and token to where the SRH instance is running. For example:
+```ts
 import {Redis} from '@upstash/redis';
 
 export const redis = new Redis({
@@ -27,84 +35,111 @@ export const redis = new Redis({
     token: "example_token",
 });
 ```
----
 
-A Redis connection pooler for serverless applications. This allows your serverless functions to talk to Redis via HTTP,
-while also not having to worry about the Redis max connection limits.
-
-The idea is you host this alongside your Redis server, to minimise latency. Your serverless functions can then talk to 
-this via HTTP.
-
-## Features
-- Allows you to talk to redis via HTTP
-- Pools redis connections
-- Automatically kills redis connections after inactivity
-- Supports multiple redis instances, and you can configure unique tokens for each
-- Fully supports the `@upstash/redis` TypeScript library.
-- Works inside of GitHub Action's services, so you can run it alongside Redis in your tests.
+# Setting up SRH
+## Via Docker command
+If you have a locally running Redis server, you can simply start an SRH container that connects to it.
+In this example, SRH will be running on port `8080`.
+
+```bash
+docker run \
+    -it -d -p 8080:80 --name srh \
+    -e SRH_MODE=env \
+    -e SRH_TOKEN=your_token_here \
+    -e SRH_CONNECTION_STRING="redis://your_server_here:6379" \
+    hiett/serverless-redis-http:latest
+```
 
-## Client usage
-This will not work with regular Redis clients, as it is over HTTP and not the redis protocol.
-However, to try and keep the project as "standardised" as possible, you can use the `@upstash/redis` TypeScript library.
-You can read about it here: [Upstash Redis GitHub](https://github.com/upstash/upstash-redis)
+## Via Docker Compose
+If you wish to run in Kubernetes, this should contain all the basics would need to set that up. However, be sure to read the Configuration Options, because you can create a setup whereby multiple Redis servers are proxied.
+```yml
+version: '3'
+services:
+  redis:
+    image: redis
+    ports:
+      - '6379:6379'
+  serverless-redis-http:
+    ports:
+      - '8079:80'
+    image: hiett/serverless-redis-http:latest
+    environment:
+      SRH_MODE: env
+      SRH_TOKEN: example_token
+      SRH_CONNECTION_STRING: 'redis://redis:6379' # Using `redis` hostname since they're in the same Docker network.
+```
 
-Soon I will add specific documentation for the endpoints so you can implement clients in other languages.
+## In GitHub Actions
+
+SRH works nicely in GitHub Actions because you can run it as a container in a job's services. Simply start a Redis server, and then
+SRH alongside it. You don't need to worry about a race condition of the Redis instance not being ready, because SRH doesn't create a Redis connection until the first command comes in.
+
+```yml
+name: Test @upstash/redis compatability
+on:
+  push:
+  workflow_dispatch:
+
+env:
+  SRH_TOKEN: example_token
+
+jobs:
+  container-job:
+    runs-on: ubuntu-latest
+    container: denoland/deno
+    services:
+      redis:
+        image: redis/redis-stack-server:6.2.6-v6 # 6.2 is the Upstash compatible Redis version
+      srh:
+        image: hiett/serverless-redis-http:latest
+        env:
+          SRH_MODE: env # We are using env mode because we are only connecting to one server.
+          SRH_TOKEN: ${{ env.SRH_TOKEN }}
+          SRH_CONNECTION_STRING: redis://redis:6379
+
+    steps:
+      # You can place your normal testing steps here. In this example, we are running SRH against the upstash/upstash-redis test suite.
+      - name: Checkout code
+        uses: actions/checkout@v3
+        with:
+          repository: upstash/upstash-redis
+
+      - name: Run @upstash/redis Test Suite
+        run: deno test -A ./pkg
+        env:
+          UPSTASH_REDIS_REST_URL: http://srh:80
+          UPSTASH_REDIS_REST_TOKEN: ${{ env.SRH_TOKEN }}
+```
 
-## Installation
-You have to options to run this:
-- Via docker: `docker pull hiett/serverless-redis-http:latest` [Docker Hub link](https://hub.docker.com/r/hiett/serverless-redis-http)
-- Via elixir: `(clone this repo)` -> `mix deps.get` -> `iex -S mix`
+# Configuration Options
 
-If you are running via Docker, you will need to mount the configuration file to `/app/srh-config/tokens.json`.\
-An example of a run command is the following:
+SRH works with multiple Redis servers, and can pool however many connections you wish it to. It will shut down un-used pools after 15 minutes of inactivity. Upon the next command, it will re-build the pool.
 
-`docker run -it -d -p 8080:80 --name srh --mount type=bind,source=$(pwd)/srh-config/tokens.json,target=/app/srh-config/tokens.json hiett/serverless-redis-http:latest`
+## Connecting to multiple Redis servers at the same time
 
-*Note that it is running on port 80*
+The examples above use environment variables in order to tell SRH which Redis server to connect to. However, you can also use a configuration JSON file, which lets you create as many connections as you wish. The token provided in each request will decide which pool is used.
 
-To configure Redis targets:\
-Create a file: `srh-config/tokens.json`
+Create a JSON file, in this example called `tokens.json`:
 ```json
 {
     "example_token": {
         "srh_id": "some_unique_identifier",
         "connection_string": "redis://localhost:6379",
         "max_connections": 3
-    } 
+    }
 }
 ```
+You can provide as many entries to the base object as you wish, and configure the number of max connections per pool. The `srh_id` is used internally to keep track of instances. It can be anything you want.
 
-Alternatively, if you are connecting to just one Redis server, you can use environment variables to set the target.
-```
-SRH_MODE="env"
-SRH_TOKEN="example_token"
-SRH_CONNECTION_STRING="redis://redis:6379"
-```
-If you use this strategy, it's important that you set `SRH_MODE=env`. This is because SRH by default uses the file strategy for backwards-compatability.
+Once you have created this, mount it to the docker container to the `/app/srh-config/tokens.json` file. Here is an example docker command:
 
-### Docker Compose
-You'll want the above `tokens.json` file but use this as your connection string:
-```json
-"connection_string": "redis://redis:6379"
-```
-docker-compose.yaml
-```yaml
-version: '3'
-services:
-  redis:
-    image: redis
-    ports:
-      - '6379:6379'
-  serverless-redis-http:
-    ports:
-      - '8079:80'
-    image: hiett/serverless-redis-http:latest
-    volumes:
-      - ./path/to/tokens.json:/app/srh-config/tokens.json
-```
+`docker run -it -d -p 8079:80 --name srh --mount type=bind,source=$(pwd)/tokens.json,target=/app/srh-config/tokens.json hiett/serverless-redis-http:latest`
+
+## Environment Variables
 
-Notes: 
-- Srh_id can be anything you want, as long as it's a string, and unique.
-- `max_connections` is the maximum number of connections for the pool.
-  - If there is inactivity, the pool will kill these connections. They will only be open while the pool is alive. The pool will re-create these connections when commands come in.
-- You can add more redis instances to connect to by adding more tokens and connection configurations. Based on the header in each request, the correct pool/connection info will be used.
+| Name | Default Value | Notes |
+| ---- | ------------- | ----- |
+| SRH_MODE | `file` | Can be `env` or `file`. If `file`, see [Connecting to multiple Redis servers](#connecting-to-multiple-redis-servers-at-the-same-time). If set to `env`, you are required to provide the following environment variables: |
+| SRH_TOKEN | `<required if SRH_MODE = env>` | Set the token that the Rest API will require |
+| SRH_CONNECTION_STRING | `<required if SRH_MODE = env>` | Sets the connection string to the Redis server. |
+| SRH_MAX_CONNECTIONS | `3` | Only used if `SRH_MODE=env`.