@quark-fw/plugin-uploads 0.1.26 → 0.1.28

package/README.md

@@ -0,0 +1,31 @@
+# @quark-fw/plugin-uploads
+
+File uploads for Quark apps: `POST /api/files` (multipart, local disk or S3-compatible storage), optional image variants via sharp, `GET /img/<id>/<variant>.<ext>` served with an immutable cache, and `authorize` / `keyFor` / `onSaved` hooks for the app.
+
+## Install
+
+```sh
+npm i @quark-fw/plugin-uploads
+```
+
+Peer: `@quark-fw/core`. `sharp` and `busboy` are dependencies; the S3 driver additionally needs `@aws-sdk/client-s3` (`npm i @aws-sdk/client-s3`, imported only when `UPLOAD_DRIVER=s3`).
+
+## Usage
+
+```ts
+import "@quark-fw/plugin-uploads"; // provides quark.uploads, POST /api/files, GET /img, /uploads
+
+// optional hooks (quark.uploads is read per request); the todo and tasktracker
+// apps run with the defaults
+quark.uploads.authorize = (req) => !!req.user; // default: any logged-in user
+quark.uploads.keyFor = ({ mimeType, originalName }) => `img/${crypto.randomUUID()}`; // default YYYY-MM/<uuid><ext>
+quark.uploads.onSaved = async (file) => file; // replace each response item, e.g. with an Image row
+```
+
+Response: `{ files: [{ key, url, size, mimeType, originalName, width?, height?, variants? }] }`; `403` when not authorized, `400` for a bad multipart body, `413` when a file exceeds `maxFileSize` (everything saved in that request is deleted).
+
+How it works: busboy streams each part (up to 20 files per request) into `quark.uploads.storage`. With `UPLOAD_VARIANTS` set, images are buffered, EXIF-rotated and resized to each width (`withoutEnlargement`, default webp, quality 80) and stored next to the original as `<key>/<name>.<ext>`. The `/img` route maps `/img/<id>/<name>.<ext>` to `<imageKeyPrefix><id>/<name>.<ext>` in storage and answers with `Cache-Control: public, max-age=31536000, immutable`; only extensions with a known inline type (png, jpg, gif, webp, avif, pdf) are served, originals without an extension are not. With the local driver, `uploads/` is served at `/uploads/<key>` with `nosniff`, and anything not in the inline list is sent as `Content-Disposition: attachment` (uploaded html/svg must never run as a page of the app). `storage.ts`, `images.ts` (`saveImage`, `processImage`, `deleteImage`) and `helpers.ts` (`createStorage`) are importable without quark, for scripts that run in a separate process.
+
+Env: `UPLOAD_MAX_SIZE` (bytes, default 10 MiB), `UPLOAD_DRIVER` (`s3` or the local disk `uploads/` by default), `UPLOAD_S3_BUCKET`, `UPLOAD_S3_REGION` (default `us-east-1`), `UPLOAD_S3_ENDPOINT` (path-style for MinIO / R2 / Yandex), `UPLOAD_S3_ACCESS_KEY`, `UPLOAD_S3_SECRET_KEY`, `UPLOAD_S3_PUBLIC_URL` (public base URL of the bucket), `UPLOAD_S3_ACL` (e.g. `public-read`), `UPLOAD_VARIANTS` (`400,800` or JSON `{"400":{"width":400},"800":{"width":800,"format":"webp"}}`), `UPLOAD_IMAGE_PREFIX` (key prefix the `/img` route serves, default `img/`).
+
+Part of the [Quark framework](https://www.npmjs.com/package/@quark-fw/core).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quark-fw/plugin-uploads",
-	"version": "0.1.26",
+	"version": "0.1.28",
 	"main": "src/index.ts",
 	"types": "src/index.ts",
 	"type": "module",
@@ -24,14 +24,14 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@quark-fw/plugin": "0.1.26",
+		"@quark-fw/plugin": "0.1.28",
 		"@types/busboy": "^1.5.4",
 		"busboy": "^1.6.0",
 		"express": "^5.2.1",
 		"sharp": "^0.34.0"
 	},
 	"peerDependencies": {
-		"@quark-fw/core": "0.1.26"
+		"@quark-fw/core": "0.1.28"
 	},
 	"devDependencies": {
 		"@types/express": "^5.0.6",

package/src/handleUpload.ts

@@ -5,6 +5,9 @@ import { safeExtension } from "./helpers.js";
 import { isImageMime, saveImage, type StoredImage } from "./images.js";
 import type { StoredFile } from "./storage.js";
 import {} from "@quark-fw/plugin-uploads/src/global.js";
+import { log as rootLog } from "@quark-fw/core/src/log.js";
+
+const log = rootLog.child({ scope: "uploads" });
 
 export const handleUpload = async (req: Request, res: Response) => {
 	const uploads = quark.uploads;
@@ -112,7 +115,7 @@ export const handleUpload = async (req: Request, res: Response) => {
 				return;
 			}
 			if (failure) {
-				console.error("[uploads]", failure);
+				log.error("upload failed", { err: failure });
 				res.status(500).json({ error: "Не удалось сохранить файл" });
 				return;
 			}
@@ -124,7 +127,7 @@ export const handleUpload = async (req: Request, res: Response) => {
 			res.json({ files });
 		} catch (e) {
 			// сбой удаления хранилища — не необработанный reject в close
-			console.error("[uploads]", e);
+			log.error("upload failed", { err: e });
 			if (!res.headersSent) {
 				res.status(500).json({ error: "Не удалось сохранить файл" });
 			}