From afd1fa7971e0cc510b6a5fbaeb68fa25e6ca85c8 Mon Sep 17 00:00:00 2001
From: Ethan Paul <24588726+enpaul@users.noreply.github.com>
Date: Sat, 13 Nov 2021 22:49:14 -0500
Subject: [PATCH] Update readme with new project direction

---
 README.md | 90 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 65 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index bf57290..d867cbb 100644
--- a/README.md
+++ b/README.md
@@ -1,42 +1,82 @@
 # kodak
 
-HTTP server for handling image uploads and thumbnail generation.
+Web server for auto-generating banners, previews, thumbnails, and more from any directory.
+Lightweight, simple, and designed for performance.
 
-This project requires [Poetry 1.0+](https://python-poetry.org/)
+Developed with [Poetry 1.0+](https://python-poetry.org/)
 
-## Implementation goals
+## Goals
 
-Support token based authentication:
+- Support defining server-side manipulation specifications
 
-```
-POST /auth/token
+  ```
+  KODAK_MANIP_FOOBAR_CROP_VERTICAL=300
+  KODAK_MANIP_FOOBAR_SCALE_HORIZONTAL=1200
+  KODAK_MANIP_FOOBAR_SCALE_STRATEGY=absolute
 
-GET /img/abcdefg.jpg?token=XYZ
-```
+  KODAK_MANIP_FIZZBUZZ_NAME=black+white
+  KODAK_MANIP_FIZZBUZZ_BLACK_AND_WHITE=true
+  KODAK_MANIP_FIZZBUZZ_SCALE_HORIZONTAL=50
+  KODAK_MANIP_FIZZBUZZ_SCALE_STRATEGY=relative
+  ```
 
-Support dynamic resolution generation:
+- Support retrieving manipulated images based on server side configuration
 
-```
-GET /img/abcdefg/100x50.jpg
-```
+  ```
+  GET /image/<name>/foobar
 
-Support server-side aliasing of resolutions to names:
+  GET /image/<name>/black+white
+  ```
 
-```
-GET /img/abcdefg/foobar.jpg  # translates to something like 120x90
-```
+- Support optionally exposing full-resolution source images
 
-Support parameter-based selection of scaling method:
+  ```
+  GET /image/<name>/original
+  ```
 
-```
-# "absolute scale horizontal", "relative scale vertical"
-GET /img/abcdefg/200x100.jpg?h=abs&v=rel
-```
+- Support caching of generated image manipulations for reuse
 
-Support both sqlite and maria storage backend
+- Support [HTTP 410](https://httpstatuses.com/410) for indicating removed images and
+  manipulations
 
-Support redis caching to relieve file system strain
+- Support optional authentication with pre-generated access tokens
 
-Support autocleaning of cached file system files to reduce directory size
+- Support static file tree management for exposure via external web server (which is faster
+  than serving files with python)
 
-Support
+- Support automatic indexing of newly added image files
+
+- Support automatic indexing of removed image files
+
+- Support arbitrary source directory structure
+
+- Support Dockerized deployment
+
+- Support bare-metal deployment (via systemd)
+
+## Non-goals
+
+- Client-defined image manipulations through publicly exposed parameters
+
+  > Manipulating images is- in the grand scheme of things- pretty resource intensive. Exposing
+  > dynamic parameters that can be cycled through to generate hundreds or thousands of
+  > permutations for every known image on a server could be used to either consume the
+  > server's entire disk or server's entire CPU.
+
+- Upload functionality
+
+  > This application should be as simple as possible. Lots of people have implemented file
+  > upload systems, synchronizers, and managers way better than I have.
+
+- Robust and flexible access control
+
+  > See above. Complex authentication can be added using a reverse proxy or any one of several
+  > dozen options for 3rd party middleware. The provided authentication is supposed to be
+  > dead simple for people who absolutely need the server to be private but absolutely cannot
+  > implement something more complicated.
+
+- Pre-creation of image manipulations
+
+  > The goal of this program is just-in-time creation of the manipulated assets with
+  > aggressive caching; first load is slow, subsequent loads are fast. For this use case
+  > there's no sense creating or storing an asset until it's known to be needed.