update README.md

Author: err0r500

Dockerfile

@@ -1,10 +1,8 @@
-# Build stage for Go proxy
 FROM golang:1.24-alpine AS builder
-
-# Install build dependencies
 RUN apk add --no-cache git
 
 WORKDIR /app
+
 # Copy Go module files
 COPY go.mod go.sum ./
 RUN go mod download
@@ -24,5 +22,5 @@ COPY start_processes.sh /usr/local/bin/
 
 EXPOSE 8080
 
-# Start proxy (which will start tigris-proxy & imgproxy)
+# Start proxy (which will start the cache proxy & imgproxy)
 CMD ["/usr/local/bin/start_processes.sh"]

LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2025 Matthieu Jacquot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,43 +1,253 @@
-# Imgproxy to Tigris Proxy
+# ImgProxy cache
 
-![CI Status](https://github.com/${{ github.repository }}/actions/workflows/ci.yml/badge.svg)
+A transparent caching reverse proxy for [imgproxy](https://imgproxy.net/) that automatically uploads processed images to S3-compatible storage (Tigris, AWS S3, MinIO, etc.).
 
-## Features
-- Dual-process architecture (Go proxy + imgproxy)
-- Non-blocking S3 writes with best-effort cleanup
-- Namespaced environment configuration
-- Structured error logging
+## What It Does
 
-## Security
-- Automatic CVE scanning
-- Distroless base image
-- Signed containers
+This application acts as a transparent layer in front of imgproxy:
 
-## Environment Variables
-| Prefix | Purpose |
-|--------|---------|
-| `PROXY_*` | Go proxy configuration |
-| `IMGPROXY_*` | Native imgproxy settings |
+1. **Receives** image processing requests
+2. **Proxies** them to imgproxy for processing
+3. **Returns** the processed image to the client immediately
+4. **Uploads** the processed image to Tigris or S3 asynchronously for future use
+
+The upload happens in the background, so client responses are not delayed. This creates a "cache-on-write" pattern where every successfully processed image is automatically stored in the target bucket.
+
+## Architecture
+
+```
+Client Request
+     ↓
+[imgproxy-cache :8080] ← This application
+     ↓
+Response → Client (immediate)
+     ↓
+S3 Upload (background)
+```
+
+The proxy:
+- Buffers the complete response in memory
+- Sends it immediately to the client
+- Spawns a goroutine to upload to S3
+- Logs upload success/failure without blocking
+
+## Use Cases
+
+- **Persistent Cache**: Ensure processed images are stored durably, even if imgproxy's local cache is cleared
+- **Multi-Region**: Process images once, store in Tigris or S3, serve from multiple regions
+- **Cost Optimization**: Reduce repeated processing of the same images
+
+## Installation
+
+### Using Docker (Recommended)
+
+The Docker image includes both imgproxy (v3.30) and the Go proxy in a single container:
 
-## Deployment
 ```bash
-docker build -t imgproxy-tigris .
+docker build -t imgproxy-cache .
+docker run -p 8080:8080 \
+  -e S3_BUCKET="your-bucket" \
+  -e AWS_ACCESS_KEY_ID="your-key" \
+  -e AWS_SECRET_ACCESS_KEY="your-secret" \
+  imgproxy-cache
+```
+
+When the container starts:
+1. imgproxy starts on `127.0.0.1:8081` (internal)
+2. The Go proxy starts on `:8080` (exposed)
+3. Both processes run under supervision - if either exits, the container stops
 
+You can pass imgproxy-specific configuration via environment variables prefixed with `IMGPROXY_`:
+
+```bash
 docker run -p 8080:8080 \
-  -e PROXY_S3_ENDPOINT="your.tigris.endpoint" \
-  -e PROXY_S3_BUCKET="your-bucket" \
-  -e PROXY_S3_REGION="auto" \
+  -e S3_BUCKET="your-bucket" \
+  -e AWS_ACCESS_KEY_ID="your-key" \
+  -e AWS_SECRET_ACCESS_KEY="your-secret" \
   -e IMGPROXY_MAX_SRC_RESOLUTION=16384 \
-  imgproxy-tigris
+  -e IMGPROXY_QUALITY=90 \
+  imgproxy-cache
 ```
 
-## Local Development
+See [imgproxy documentation](https://docs.imgproxy.net/configuration) for all available options.
+
+### From Source
+
 ```bash
-docker-compose -f docker-compose.local.yml up --build
-aws --endpoint-url=http://localhost:4566 s3 mb s3://test-bucket
+go build -o imgproxy-cache .
+./imgproxy-cache
 ```
 
-## Operational Notes
-- S3 writes happen in parallel with client streaming
-- Partial uploads are automatically cleaned up
-- Process crashes are handled by supervisord
+**Note**: When running from source, you must have imgproxy running separately on `localhost:8081`. The application will wait up to 30 seconds for imgproxy to become healthy before starting.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `S3_BUCKET` | **Yes** | - | S3 bucket name where images will be stored |
+| `S3_FOLDER` | No | `""` | Prefix/folder path within the bucket |
+| `S3_ENDPOINT` | No | `https://fly.storage.tigris.dev` | S3-compatible endpoint URL |
+| `IMGPROXY_BIND` | No | `:8080` | Address and port for the proxy to bind to |
+| `HEALTH_CHECK_TIMEOUT_IN_SEC` | No | `30` | Seconds to wait for imgproxy to become healthy |
+
+### AWS Credentials
+
+The application uses the AWS SDK v2, which automatically loads credentials from:
+- Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
+- Shared credentials file (`~/.aws/credentials`)
+- IAM roles (when running on EC2/ECS/Lambda)
+- Web identity tokens (when running on EKS)
+
+See [AWS SDK documentation](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/) for full details.
+
+## How Caching Works
+
+### Key Generation
+
+S3 keys are generated by MD5 hashing the imgproxy URL path:
+
+```
+Request: /resize:fill:300:300/plain/https://example.com/image.jpg
+S3 Key:  a3f8c9d2e1b4f7a6c8d9e2f1b3a4c5d6
+```
+
+This ensures:
+- **Consistent**: Same URL always maps to the same S3 key
+- **Compact**: Keys are fixed-length 32 characters
+- **Safe**: No special characters or path traversal issues
+
+### Upload Behavior
+
+- **Only successful responses** (HTTP 200) are uploaded
+- **Uploads are asynchronous** - client doesn't wait for S3 confirmation
+- **Failed uploads are logged** but don't affect the client response
+- **No deduplication** - same request will re-upload (consider implementing checks)
+
+### Storage Structure
+
+```
+s3://your-bucket/
+  └── processed/              (if S3_FOLDER is set)
+      ├── a3f8c9d2e1b4f7a6...  (image 1)
+      ├── b2e7d8c1f0a9e3b7...  (image 2)
+      └── c9f1a2b3e4d5c6a7...  (image 3)
+```
+
+## Usage Example
+
+### Start the Service
+
+```bash
+export S3_BUCKET="my-images"
+export AWS_ACCESS_KEY_ID="your-key"
+export AWS_SECRET_ACCESS_KEY="your-secret"
+
+./imgproxy-cache
+```
+
+### Process an Image
+
+```bash
+# Request an image through the proxy
+curl http://localhost:8080/resize:fill:300:300/plain/https://example.com/cat.jpg > output.jpg
+
+# The processed image is:
+# 1. Returned immediately to your curl command
+# 2. Uploaded to S3 in the background
+```
+
+### Check Logs
+
+```
+2025/10/20 10:30:00 INFO Waiting for imgproxy to be ready...
+2025/10/20 10:30:01 INFO imgproxy is ready
+2025/10/20 10:30:15 INFO Uploaded to S3 path=/resize:fill:300:300/plain/https://example.com/cat.jpg bucket=my-images key=a3f8c9d2e1b4f7a6c8d9e2f1b3a4c5d6
+```
+
+## Example client code
+### HTML
+```html
+<img
+  src="https://process-image-url"
+  onerror="this.onerror=null; this.src='https://proxy-url/image-processing-params/original-image-url';"
+/>
+```
+
+### Elixir
+
+```elixir
+  @doc """
+  Renders an image with proxy URL transformation.
+  The image URL will be transformed to: <image_proxy_url>/<dimensions>/<image_url>
+  """
+  attr :src, :string, required: true
+  attr :dimensions, :string, required: true
+  attr :resize_mode, :string, default: "fit", values: ["fit", "fill"]
+  attr :class, :string, default: nil
+  attr :alt, :string, default: nil
+
+  def image(assigns) do
+    img_path =
+      "/rs:#{assigns.resize_mode}:#{assigns.dimensions}:1/dpr:2/g:ce/" <>
+        Base.encode64(assigns.src) <> ".webp"
+
+    signature =
+      :crypto.mac(
+        :hmac,
+        :sha256,
+        Base.decode16!(
+          System.get_env("IMGPROXY_KEY"),
+          case: :lower
+        ),
+        Base.decode16!(
+          System.get_env("IMGPROXY_SALT"),
+          case: :lower
+        ) <> img_path
+      )
+      |> Base.url_encode64(padding: false)
+
+    full_path = "/" <> signature <> img_path
+
+    assigns =
+      assigns
+      |> assign(:proxy_src, "#{Application.get_env(:manage, :image_proxy_url)}#{full_path}")
+      |> assign(
+        :cached_src,
+        Application.get_env(:manage, :image_cache_url) <>
+          "/" <>
+          (:crypto.hash(:md5, full_path)
+           |> Base.encode16(case: :lower))
+      )
+
+    ~H"""
+    <img
+      src={@cached_src}
+      class={@class}
+      alt={@alt}
+      onerror={"this.onerror=null; this.src='#{@proxy_src}';"}
+    />
+    """
+  end
+```
+
+## Development
+
+### Testing
+
+```bash
+go test -v ./...
+```
+
+## Limitations & Considerations
+
+- **Memory Usage**: Entire response is buffered in memory before upload
+- **No Retry Logic**: Failed S3 uploads are not retried
+- **No Deduplication**: Same image can be uploaded multiple times
+- **No Cleanup**: Old/unused images are never deleted from S3
+- **No Validation**: Uploads happen even if the same key already exists in S3
+
+## License
+
+[MIT LICENSE](./LICENSE.md)