Architecture

Last updated


This page shows, in one overview diagram, how the layers of node-image-server relate and what each one owns.

System Overview


graph TB
    Client[Client] --> Worker[Cloudflare Worker · worker/index.js]
    Client --> Nginx[Nginx · config/nginx/nodejs.conf]
    Worker --> Nginx
    Nginx -->|/c/img/| App[Express cluster · app/app.ts]
    Nginx -->|/upload/ · /del/ · /| App
    App --> MW[Middlewares · app/src/middlewares]
    MW --> Router[Router · app/src/router]
    Router --> GET[GetFromPath · sharp]
    Router --> POST[PostToPath · multer]
    Router --> DEL[DeleteFromPath]
    GET --> Upload[(storage/image/upload)]
    GET --> Cache[(storage/image/cache)]
    POST --> Upload
    DEL --> Trash[(upload/.trash/YYYY-MM-DD)]
  1. graph TB
  2. Client[Client] --> Worker[Cloudflare Worker · worker/index.js]
  3. Client --> Nginx[Nginx · config/nginx/nodejs.conf]
  4. Worker --> Nginx
  5. Nginx -->|/c/img/| App[Express cluster · app/app.ts]
  6. Nginx -->|/upload/ · /del/ · /| App
  7. App --> MW[Middlewares · app/src/middlewares]
  8. MW --> Router[Router · app/src/router]
  9. Router --> GET[GetFromPath · sharp]
  10. Router --> POST[PostToPath · multer]
  11. Router --> DEL[DeleteFromPath]
  12. GET --> Upload[(storage/image/upload)]
  13. GET --> Cache[(storage/image/cache)]
  14. POST --> Upload
  15. DEL --> Trash[(upload/.trash/YYYY-MM-DD)]

Layers


LayerLocationResponsibility
CDNworker/index.jsCaches for 7 days keyed on URL plus query string; forwards to the origin on a miss
Reverse proxyconfig/nginx/nodejs.confproxy_cache for /c/img/, security headers, dotfile denial, HTTP method and upload size limits
Process managementapp/app.json, app/app.tsPM2 loads via ts-node; the primary forks workers and respawns them on exit
Middlewareapp/src/middlewares/Parsing, CORS, request logging, HTML minification, dropping requests without User-Agent
Routingapp/src/router/Dispatches by HTTP method to the GET / POST / DELETE sub-routers
HandlersGetFromPath, PostToPath, DeleteFromPathConversion and caching, upload, moving to trash
Storageapp/storage/image/upload/ originals, cache/ conversions, upload/.trash/ deleted items

Cross-Cutting Principles


PrincipleImplementation
Process onceConversions are written as cache files, and the edge layers cache on top
Never hard-deleteDeletion always renameSyncs into today's trash
Never upscaleEvery size parameter is capped at the original dimensions

Where It Fits


node-image-server is built on sharp, the libvips-based Node.js image processing library, and wraps it in an HTTP image server with its own storage. unjs/ipx is also a sharp-based image optimizer: it serves a directory or a list of allowed domains and puts modifiers in the URL path (/w_512,f_webp/...). jimmynicol/image-resizer is an Express app that sits as a CDN custom origin and pulls originals from sources such as S3. node-image-server keeps originals on its own disk instead: clients upload through POST /upload, read variants through query parameters on GET /c/img, and delete into a dated trash, while each variant is written once as a cache file behind the shipped Nginx proxy_cache and Cloudflare Worker configs.

Further Reading


中文