S3 (MinIO) Object Storage + Feed Image Uploads — Implementation Plan¶
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Stand up S3-compatible object storage (MinIO) behind a provider-agnostic seam, and ship image uploads on the RMHark feed served through an app-proxied route.
Architecture: A single storage module (lib/storage/s3.server.ts) is the only code that talks to the object store via @aws-sdk/client-s3; everything else is provider-blind. Feed posts store stable internal URLs (/api/feed/image/<filename>) so swapping MinIO→Cloudflare R2 later is config-only. Pure helpers (key building, filename safety, content-type) live in lib/storage/keys.ts and are unit-tested; the upload/serve routes mirror the existing avatar routes exactly.
Tech Stack: TanStack React Router file routes, Node, Prisma/Postgres, @aws-sdk/client-s3, MinIO, Docker Compose, Helm (k3s), Vitest, pnpm.
Global Constraints¶
Package manager is pnpm (
pnpm add,pnpm exec,pnpm run). Never use npm/yarn.Path alias
@resolves to the repo root (vitest.config.ts+ tsconfig). Import libs as@/lib/....Vitest only runs files matching
vitest.config.tsincludeglobs. New unit tests MUST live underlib/__tests__/**/*.test.tsto be picked up. Run withnode_modules/.bin/vitest run.All provider/SDK knowledge stays inside
lib/storage/s3.server.ts. No other file imports@aws-sdk/*.Server-only modules use the
.server.tssuffix and@/lib/prisma.server/@/lib/authconventions.Routes are TanStack
createFileRoute('/exact/path')({ server: { handlers: { GET/POST } } }). Handlers receive{ request, params }and return aResponse.Image validation is by magic bytes via
validateImageBufferfrom@/lib/slice-it/upload-validation(it has its own 10 MB ceiling; enforce the 5 MB feed cap BEFORE calling it, exactly likeapp/routes/api/profile/avatar.ts).Feed limits: max 4 images per post, max 5 MB per image. Allowed types: PNG, JPEG, GIF, WebP.
Soft-deleted posts (
RMHark.deletedAt) keep their objects; cleanup is a deferred future sweeper, NOT in this plan.
Task 1: Pure storage helpers (key building, filename safety, content-type)¶
Files:
Create:
lib/storage/keys.tsTest:
lib/__tests__/storage-keys.test.ts
Interfaces:
Produces:
FEED_IMAGE_PREFIX = "rmharks/"(const string)isSafeFilename(name: string): boolean— true only for^[A-Za-z0-9._-]+$(no slashes, no..)contentTypeForFilename(filename: string): string— maps.png/.jpg/.jpeg/.webp/.gif→ image MIME, elseapplication/octet-streamfeedImageKey(filename: string): string— returnsrmharks/<filename>feedImageUrl(filename: string): string— returns/api/feed/image/<filename>
Step 1: Write the failing test
// lib/__tests__/storage-keys.test.ts
import { describe, it, expect } from "vitest";
import {
FEED_IMAGE_PREFIX,
isSafeFilename,
contentTypeForFilename,
feedImageKey,
feedImageUrl,
} from "@/lib/storage/keys";
describe("storage keys", () => {
it("accepts safe filenames and rejects traversal/slashes", () => {
expect(isSafeFilename("u1-123-456-pic.png")).toBe(true);
expect(isSafeFilename("a_b.webp")).toBe(true);
expect(isSafeFilename("../etc/passwd")).toBe(false);
expect(isSafeFilename("dir/file.png")).toBe(false);
expect(isSafeFilename("..")).toBe(false);
expect(isSafeFilename("")).toBe(false);
});
it("maps extensions to content types", () => {
expect(contentTypeForFilename("x.png")).toBe("image/png");
expect(contentTypeForFilename("x.JPG")).toBe("image/jpeg");
expect(contentTypeForFilename("x.jpeg")).toBe("image/jpeg");
expect(contentTypeForFilename("x.webp")).toBe("image/webp");
expect(contentTypeForFilename("x.gif")).toBe("image/gif");
expect(contentTypeForFilename("x.bin")).toBe("application/octet-stream");
});
it("builds bucket keys and public urls", () => {
expect(FEED_IMAGE_PREFIX).toBe("rmharks/");
expect(feedImageKey("u1-1-2-p.png")).toBe("rmharks/u1-1-2-p.png");
expect(feedImageUrl("u1-1-2-p.png")).toBe("/api/feed/image/u1-1-2-p.png");
});
});
Step 2: Run test to verify it fails
Run: node_modules/.bin/vitest run lib/__tests__/storage-keys.test.ts
Expected: FAIL — cannot resolve @/lib/storage/keys.
Step 3: Write minimal implementation
// lib/storage/keys.ts
export const FEED_IMAGE_PREFIX = "rmharks/";
const SAFE_FILENAME_RE = /^[A-Za-z0-9._-]+$/;
export function isSafeFilename(name: string): boolean {
if (!name || name === "." || name === "..") return false;
return SAFE_FILENAME_RE.test(name);
}
const CONTENT_TYPES: Record<string, string> = {
".png": "image/png",
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".webp": "image/webp",
".gif": "image/gif",
};
export function contentTypeForFilename(filename: string): string {
const dot = filename.lastIndexOf(".");
const ext = dot >= 0 ? filename.slice(dot).toLowerCase() : "";
return CONTENT_TYPES[ext] ?? "application/octet-stream";
}
export function feedImageKey(filename: string): string {
return `${FEED_IMAGE_PREFIX}${filename}`;
}
export function feedImageUrl(filename: string): string {
return `/api/feed/image/${filename}`;
}
Step 4: Run test to verify it passes
Run: node_modules/.bin/vitest run lib/__tests__/storage-keys.test.ts
Expected: PASS (3 tests).
Step 5: Commit
git add lib/storage/keys.ts lib/__tests__/storage-keys.test.ts
git commit -m "feat(storage): pure helpers for feed image keys + filename safety"
Task 2: S3 client wrapper (the provider seam)¶
Files:
Create:
lib/storage/s3.server.tsTest:
lib/__tests__/storage-s3.test.tsModify:
package.json(adds@aws-sdk/client-s3dependency)
Interfaces:
Consumes: nothing from earlier tasks.
Produces:
putObject(key: string, body: Buffer, contentType: string): Promise<void>getObject(key: string): Promise<{ body: Buffer; contentType: string } | null>—nullwhen the object is missing (NoSuchKey)deleteObject(key: string): Promise<void>objectExists(key: string): Promise<boolean>getBucket(): string— the configured bucket name
(Note: this refines the spec’s
getObjectStreamto a Buffer-returninggetObject, matching the codebase’s buffer-based serve routes inapp/routes/api/profile/avatar/$filename.ts.)Step 1: Install the SDK
Run: pnpm add @aws-sdk/client-s3
Expected: package.json gains @aws-sdk/client-s3 under dependencies; pnpm-lock.yaml updates.
Step 2: Write the failing test
The test mocks @aws-sdk/client-s3 so it is deterministic and offline. It asserts the wrapper issues the right commands and maps a missing object to null.
// lib/__tests__/storage-s3.test.ts
import { describe, it, expect, vi, beforeEach } from "vitest";
const sendMock = vi.fn();
vi.mock("@aws-sdk/client-s3", () => {
class S3Client {
send = sendMock;
}
class NoSuchKey extends Error {
name = "NoSuchKey";
}
return {
S3Client,
PutObjectCommand: vi.fn((input) => ({ __type: "Put", input })),
GetObjectCommand: vi.fn((input) => ({ __type: "Get", input })),
DeleteObjectCommand: vi.fn((input) => ({ __type: "Delete", input })),
HeadObjectCommand: vi.fn((input) => ({ __type: "Head", input })),
NoSuchKey,
};
});
beforeEach(() => {
sendMock.mockReset();
process.env.S3_ENDPOINT = "http://minio:9000";
process.env.S3_REGION = "us-east-1";
process.env.S3_ACCESS_KEY_ID = "key";
process.env.S3_SECRET_ACCESS_KEY = "secret";
process.env.S3_BUCKET = "rmh-media";
process.env.S3_FORCE_PATH_STYLE = "true";
vi.resetModules();
});
describe("s3 wrapper", () => {
it("putObject sends a PutObjectCommand with bucket/key/body", async () => {
sendMock.mockResolvedValue({});
const { putObject, getBucket } = await import("@/lib/storage/s3.server");
await putObject("rmharks/a.png", Buffer.from("x"), "image/png");
expect(getBucket()).toBe("rmh-media");
const cmd = sendMock.mock.calls[0][0];
expect(cmd.__type).toBe("Put");
expect(cmd.input).toMatchObject({
Bucket: "rmh-media",
Key: "rmharks/a.png",
ContentType: "image/png",
});
});
it("getObject returns body+contentType from the stream", async () => {
sendMock.mockResolvedValue({
ContentType: "image/png",
Body: { transformToByteArray: async () => new Uint8Array([1, 2, 3]) },
});
const { getObject } = await import("@/lib/storage/s3.server");
const result = await getObject("rmharks/a.png");
expect(result?.contentType).toBe("image/png");
expect(Array.from(result!.body)).toEqual([1, 2, 3]);
});
it("getObject returns null when the key is missing", async () => {
const { NoSuchKey } = await import("@aws-sdk/client-s3");
sendMock.mockRejectedValue(new NoSuchKey("missing"));
const { getObject } = await import("@/lib/storage/s3.server");
expect(await getObject("rmharks/missing.png")).toBeNull();
});
});
Step 3: Run test to verify it fails
Run: node_modules/.bin/vitest run lib/__tests__/storage-s3.test.ts
Expected: FAIL — cannot resolve @/lib/storage/s3.server.
Step 4: Write minimal implementation
// lib/storage/s3.server.ts
import {
S3Client,
PutObjectCommand,
GetObjectCommand,
DeleteObjectCommand,
HeadObjectCommand,
NoSuchKey,
} from "@aws-sdk/client-s3";
function requireEnv(name: string): string {
const v = process.env[name];
if (!v) throw new Error(`Missing required env var ${name}`);
return v;
}
function getBucket(): string {
return requireEnv("S3_BUCKET");
}
let client: S3Client | null = null;
function getClient(): S3Client {
if (client) return client;
client = new S3Client({
endpoint: requireEnv("S3_ENDPOINT"),
region: process.env.S3_REGION || "us-east-1",
forcePathStyle: process.env.S3_FORCE_PATH_STYLE !== "false",
credentials: {
accessKeyId: requireEnv("S3_ACCESS_KEY_ID"),
secretAccessKey: requireEnv("S3_SECRET_ACCESS_KEY"),
},
});
return client;
}
export async function putObject(
key: string,
body: Buffer,
contentType: string
): Promise<void> {
await getClient().send(
new PutObjectCommand({
Bucket: getBucket(),
Key: key,
Body: body,
ContentType: contentType,
})
);
}
export async function getObject(
key: string
): Promise<{ body: Buffer; contentType: string } | null> {
try {
const res = await getClient().send(
new GetObjectCommand({ Bucket: getBucket(), Key: key })
);
const bytes = await (res.Body as {
transformToByteArray: () => Promise<Uint8Array>;
}).transformToByteArray();
return {
body: Buffer.from(bytes),
contentType: res.ContentType || "application/octet-stream",
};
} catch (err) {
if (err instanceof NoSuchKey || (err as { name?: string })?.name === "NoSuchKey") {
return null;
}
throw err;
}
}
export async function deleteObject(key: string): Promise<void> {
await getClient().send(
new DeleteObjectCommand({ Bucket: getBucket(), Key: key })
);
}
export async function objectExists(key: string): Promise<boolean> {
try {
await getClient().send(
new HeadObjectCommand({ Bucket: getBucket(), Key: key })
);
return true;
} catch {
return false;
}
}
export { getBucket };
Step 5: Run test to verify it passes
Run: node_modules/.bin/vitest run lib/__tests__/storage-s3.test.ts
Expected: PASS (3 tests).
Step 6: Commit
git add lib/storage/s3.server.ts lib/__tests__/storage-s3.test.ts package.json pnpm-lock.yaml
git commit -m "feat(storage): provider-agnostic S3 wrapper (put/get/delete/head)"
Task 3: Infra — env vars, MinIO in Docker Compose, MinIO Helm template¶
Files:
Modify:
.env.exampleModify:
docker-compose.ymlCreate:
deploy/helm/rmhstudios/templates/minio.yamlModify:
deploy/helm/rmhstudios/values.yaml
Interfaces:
Produces the runtime env contract consumed by Task 2:
S3_ENDPOINT,S3_REGION,S3_ACCESS_KEY_ID,S3_SECRET_ACCESS_KEY,S3_BUCKET,S3_FORCE_PATH_STYLE.Step 1: Document the env contract in
.env.example
Append this block to .env.example:
# ─── Object storage (S3-compatible: MinIO now, Cloudflare R2 later) ──────────
# MinIO defaults match the docker-compose `minio` service below.
# To migrate to R2: change ENDPOINT to your R2 S3 API URL, set the R2 access
# keys, set S3_FORCE_PATH_STYLE=false, and copy objects with rclone.
S3_ENDPOINT=http://minio:9000
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=rmhminio
S3_SECRET_ACCESS_KEY=rmhminio-dev-secret
S3_BUCKET=rmh-media
S3_FORCE_PATH_STYLE=true
Step 2: Add the
minio+minio-initservices todocker-compose.yml
Add these two services under the existing services: map (after bot-worker). minio-init creates the bucket once on startup, then exits.
# ─── MinIO (S3-compatible object storage) ──────────────────────────────────
minio:
image: minio/minio:latest
container_name: ${COMPOSE_PROJECT_NAME:-rmhstudios}-minio
restart: unless-stopped
command: ["server", "/data", "--console-address", ":9001"]
environment:
- MINIO_ROOT_USER=${S3_ACCESS_KEY_ID:-rmhminio}
- MINIO_ROOT_PASSWORD=${S3_SECRET_ACCESS_KEY:-rmhminio-dev-secret}
ports:
- "127.0.0.1:9000:9000"
- "127.0.0.1:9001:9001"
volumes:
- ${MINIO_DATA_PATH:-./minio-data}:/data
healthcheck:
test: ["CMD", "mc", "ready", "local"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
# ─── MinIO bucket bootstrap (creates the bucket, then exits) ────────────────
minio-init:
image: minio/mc:latest
container_name: ${COMPOSE_PROJECT_NAME:-rmhstudios}-minio-init
depends_on:
minio:
condition: service_healthy
entrypoint: >
/bin/sh -c "
mc alias set local http://minio:9000 ${S3_ACCESS_KEY_ID:-rmhminio} ${S3_SECRET_ACCESS_KEY:-rmhminio-dev-secret} &&
mc mb --ignore-existing local/${S3_BUCKET:-rmh-media} &&
echo 'bucket ready';
"
restart: "no"
Step 3: Verify the compose file parses
Run: docker compose -f docker-compose.yml config >/dev/null && echo OK
Expected: prints OK (no YAML/interpolation errors). If Docker is unavailable in the environment, instead run python3 -c "import yaml,sys; yaml.safe_load(open('docker-compose.yml'))" && echo OK.
Step 4: Add the MinIO Helm template
# deploy/helm/rmhstudios/templates/minio.yaml
{{- if .Values.minio.enabled }}
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: {{ include "rmhstudios.fullname" . }}-minio
labels:
{{- include "rmhstudios.labels" . | nindent 4 }}
spec:
accessModes:
- ReadWriteOnce
storageClassName: {{ .Values.minio.storageClass | quote }}
resources:
requests:
storage: {{ .Values.minio.size | quote }}
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "rmhstudios.fullname" . }}-minio
labels:
{{- include "rmhstudios.labels" . | nindent 4 }}
spec:
replicas: 1
selector:
matchLabels:
{{- include "rmhstudios.selectorLabels" . | nindent 6 }}
app.kubernetes.io/component: minio
template:
metadata:
labels:
{{- include "rmhstudios.selectorLabels" . | nindent 8 }}
app.kubernetes.io/component: minio
spec:
containers:
- name: minio
image: {{ .Values.minio.image | quote }}
args: ["server", "/data", "--console-address", ":9001"]
envFrom:
- secretRef:
name: {{ .Values.secretName }}
env:
- name: MINIO_ROOT_USER
valueFrom:
secretKeyRef:
name: {{ .Values.secretName }}
key: S3_ACCESS_KEY_ID
- name: MINIO_ROOT_PASSWORD
valueFrom:
secretKeyRef:
name: {{ .Values.secretName }}
key: S3_SECRET_ACCESS_KEY
ports:
- containerPort: 9000
- containerPort: 9001
volumeMounts:
- name: data
mountPath: /data
volumes:
- name: data
persistentVolumeClaim:
claimName: {{ include "rmhstudios.fullname" . }}-minio
---
apiVersion: v1
kind: Service
metadata:
name: {{ include "rmhstudios.fullname" . }}-minio
labels:
{{- include "rmhstudios.labels" . | nindent 4 }}
spec:
selector:
{{- include "rmhstudios.selectorLabels" . | nindent 4 }}
app.kubernetes.io/component: minio
ports:
- name: s3
port: 9000
targetPort: 9000
- name: console
port: 9001
targetPort: 9001
{{- end }}
Step 5: Add MinIO defaults to
values.yaml
Insert this block after the data: block in deploy/helm/rmhstudios/values.yaml:
# MinIO S3-compatible object storage (single-node). The app reaches it via the
# S3_ENDPOINT secret value, e.g. http://rmhstudios-minio:9000.
# MULTI-NODE/PROD: disable and point S3_ENDPOINT at Cloudflare R2 instead.
minio:
enabled: true
image: minio/minio:latest
size: 20Gi
storageClass: local-path
Step 6: Verify the chart templates render
Run: helm template deploy/helm/rmhstudios | grep -c "kind: Deployment"
Expected: a count one higher than before (the new MinIO Deployment renders). If helm is unavailable, instead run python3 -c "import yaml; list(yaml.safe_load_all(open('deploy/helm/rmhstudios/templates/minio.yaml').read().replace('{{','#{{').replace('}}','}}#')))" ; echo "template authored" as a smoke check and note manual helm template verification is required before deploy.
Step 7: Commit
git add .env.example docker-compose.yml deploy/helm/rmhstudios/templates/minio.yaml deploy/helm/rmhstudios/values.yaml
git commit -m "feat(infra): MinIO in compose + helm; S3 env contract"
Task 4: Data model + schema wiring (imageUrls everywhere)¶
Files:
Modify:
prisma/schema.prisma:990(RMHark model)Modify:
lib/rmhark-schema.tsModify:
lib/feed-types.tsTest:
lib/__tests__/rmhark-schema.test.ts
Interfaces:
Consumes:
feedImageUrlshape from Task 1 (/api/feed/image/<filename>).Produces:
RMHark.imageUrls: String[]column.createRMHarkSchemaacceptsimageUrls?: string[](each matching^/api/feed/image/[A-Za-z0-9._-]+$, max 4) and treats a non-emptyimageUrlsas valid post content.FeedItem.imageUrls?: string[].
Step 1: Add the column to the Prisma model
In prisma/schema.prisma, in model RMHark, add imageUrls right after the gifUrl line:
gifUrl String? @db.Text
imageUrls String[]
Step 2: Create and apply the migration
Run: pnpm exec prisma migrate dev --name rmhark_image_urls
Expected: a new migration under prisma/migrations/ adding image_urls text[]; Prisma Client regenerates. (If the dev DB is unreachable, run pnpm exec prisma generate and hand-write the migration SQL ALTER TABLE "rmheet" ADD COLUMN "imageUrls" TEXT[] NOT NULL DEFAULT '{}'; in a new timestamped migration dir.)
Step 3: Write the failing schema test
// lib/__tests__/rmhark-schema.test.ts
import { describe, it, expect } from "vitest";
import { createRMHarkSchema } from "@/lib/rmhark-schema";
describe("createRMHarkSchema imageUrls", () => {
it("accepts a post with only images (no text/poll/gif)", () => {
const r = createRMHarkSchema.safeParse({
imageUrls: ["/api/feed/image/u1-1-2-pic.png"],
});
expect(r.success).toBe(true);
});
it("rejects more than 4 images", () => {
const r = createRMHarkSchema.safeParse({
content: "hi",
imageUrls: [
"/api/feed/image/a.png",
"/api/feed/image/b.png",
"/api/feed/image/c.png",
"/api/feed/image/d.png",
"/api/feed/image/e.png",
],
});
expect(r.success).toBe(false);
});
it("rejects image urls that are not feed-image paths", () => {
const r = createRMHarkSchema.safeParse({
imageUrls: ["https://evil.example/x.png"],
});
expect(r.success).toBe(false);
});
it("still rejects a fully empty post", () => {
const r = createRMHarkSchema.safeParse({ imageUrls: [] });
expect(r.success).toBe(false);
});
});
Step 4: Run the test to verify it fails
Run: node_modules/.bin/vitest run lib/__tests__/rmhark-schema.test.ts
Expected: FAIL — imageUrls not yet in the schema (empty-only & image-only cases behave wrong).
Step 5: Update
createRMHarkSchema
In lib/rmhark-schema.ts, add the constant and field, and extend the refine. Add near the other limits:
export const MAX_RMHARK_IMAGES = 4;
const feedImageUrlSchema = z
.string()
.regex(/^\/api\/feed\/image\/[A-Za-z0-9._-]+$/, "Invalid image reference");
Change the object + refine to:
export const createRMHarkSchema = z
.object({
content: z
.string()
.max(MAX_RMHARK_LENGTH, `RMHark must be at most ${MAX_RMHARK_LENGTH} characters`)
.optional()
.default(""),
poll: pollSchema.optional(),
gifUrl: gifUrlSchema.optional(),
imageUrls: z
.array(feedImageUrlSchema)
.max(MAX_RMHARK_IMAGES, `At most ${MAX_RMHARK_IMAGES} images allowed`)
.optional(),
})
.refine(
(data) =>
data.content.trim().length > 0 ||
data.poll ||
data.gifUrl ||
(data.imageUrls?.length ?? 0) > 0,
{ message: "Post must have text, a poll, or an image/GIF" }
);
Step 6: Add
imageUrlstoFeedItem
In lib/feed-types.ts, in the FeedItem interface, add right after the gifUrl?: string; line (line ~58):
imageUrls?: string[];
Step 7: Run the schema test to verify it passes
Run: node_modules/.bin/vitest run lib/__tests__/rmhark-schema.test.ts
Expected: PASS (4 tests).
Step 8: Commit
git add prisma/schema.prisma prisma/migrations lib/rmhark-schema.ts lib/feed-types.ts lib/__tests__/rmhark-schema.test.ts
git commit -m "feat(feed): add imageUrls to RMHark model, schema, and FeedItem"
Task 5: Feed image upload route¶
Files:
Create:
app/routes/api/rmharks/image.tsModify:
lib/slice-it/upload-validation.ts(exportdetectImageExt)Test:
lib/__tests__/detect-image-ext.test.ts
Interfaces:
Consumes:
putObject(Task 2);feedImageKey,feedImageUrl(Task 1);validateImageBuffer(existing);detectImageExt(this task).Produces:
POST /api/rmharks/imageacceptingmultipart/form-datawith one or moreimagesfields; returns{ urls: string[] }(200) of/api/feed/image/<filename>values.detectImageExt(buffer: Buffer): ".png" | ".jpg" | ".webp" | ".gif" | nullStep 1: Write the failing test for
detectImageExt
// lib/__tests__/detect-image-ext.test.ts
import { describe, it, expect } from "vitest";
import { detectImageExt } from "@/lib/slice-it/upload-validation";
describe("detectImageExt", () => {
it("detects PNG by magic bytes", () => {
const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
expect(detectImageExt(png)).toBe(".png");
});
it("detects JPEG", () => {
expect(detectImageExt(Buffer.from([0xff, 0xd8, 0xff, 0x00]))).toBe(".jpg");
});
it("detects GIF", () => {
expect(detectImageExt(Buffer.from("GIF89a"))).toBe(".gif");
});
it("returns null for unknown", () => {
expect(detectImageExt(Buffer.from([0x00, 0x01, 0x02]))).toBeNull();
});
});
Step 2: Run it to verify it fails
Run: node_modules/.bin/vitest run lib/__tests__/detect-image-ext.test.ts
Expected: FAIL — detectImageExt is not exported.
Step 3: Add
detectImageExttolib/slice-it/upload-validation.ts
Append this export (it reuses the same signatures already defined in the file):
/** Detect a canonical image extension from magic bytes, or null if unknown. */
export function detectImageExt(
buffer: Buffer
): ".png" | ".jpg" | ".webp" | ".gif" | null {
if (buffer.length >= 8 && buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) return ".png";
if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) return ".jpg";
if (buffer.length >= 12 && buffer.toString("ascii", 0, 4) === "RIFF" && buffer.toString("ascii", 8, 12) === "WEBP") return ".webp";
if (buffer.length >= 6 && (buffer.toString("ascii", 0, 6) === "GIF87a" || buffer.toString("ascii", 0, 6) === "GIF89a")) return ".gif";
return null;
}
Step 4: Run it to verify it passes
Run: node_modules/.bin/vitest run lib/__tests__/detect-image-ext.test.ts
Expected: PASS (4 tests).
Step 5: Create the upload route
// app/routes/api/rmharks/image.ts
import { createFileRoute } from '@tanstack/react-router';
import { auth } from "@/lib/auth";
import { rateLimit, getClientIp } from "@/lib/rate-limit";
import {
validateImageBuffer,
detectImageExt,
} from "@/lib/slice-it/upload-validation";
import { putObject } from "@/lib/storage/s3.server";
import { feedImageKey, feedImageUrl, contentTypeForFilename } from "@/lib/storage/keys";
const FEED_IMAGE_MAX_BYTES = 5 * 1024 * 1024; // 5 MB per image
const MAX_IMAGES = 4;
export const Route = createFileRoute('/api/rmharks/image')({
server: {
handlers: {
POST: async ({ request }) => {
try {
const session = await auth.api.getSession({ headers: request.headers });
if (!session) {
return Response.json({ error: "Unauthorized" }, { status: 401 });
}
const ip = getClientIp(request);
const { allowed, retryAfter } = rateLimit(ip, {
limit: 10,
windowMs: 60_000,
prefix: "rmhark-image-upload",
});
if (!allowed) {
return Response.json(
{ error: "Too many uploads. Try again later." },
{ status: 429, headers: { "Retry-After": String(retryAfter) } }
);
}
const formData = await request.formData();
const files = formData.getAll("images").filter((f): f is File => f instanceof File && f.size > 0);
if (files.length === 0) {
return Response.json({ error: "No file provided" }, { status: 400 });
}
if (files.length > MAX_IMAGES) {
return Response.json(
{ error: `At most ${MAX_IMAGES} images per post.` },
{ status: 400 }
);
}
const urls: string[] = [];
for (const file of files) {
if (file.size > FEED_IMAGE_MAX_BYTES) {
return Response.json(
{ error: `Image too large. Maximum size is ${FEED_IMAGE_MAX_BYTES / 1024 / 1024} MB.` },
{ status: 400 }
);
}
const buffer = Buffer.from(await file.arrayBuffer());
const validation = validateImageBuffer(buffer);
if (!validation.ok) {
return Response.json({ error: validation.error }, { status: 400 });
}
const ext = detectImageExt(buffer);
if (!ext) {
return Response.json({ error: "Unsupported image format." }, { status: 400 });
}
const uniqueSuffix = `${Date.now()}-${Math.round(Math.random() * 1e9)}`;
const filename = `${session.user.id}-${uniqueSuffix}${ext}`;
await putObject(feedImageKey(filename), buffer, contentTypeForFilename(filename));
urls.push(feedImageUrl(filename));
}
return Response.json({ urls });
} catch (error) {
console.error("Feed image upload error:", error);
return Response.json({ error: "Internal Server Error" }, { status: 500 });
}
},
},
},
});
Step 6: Typecheck the new route
Run: pnpm exec tsc --noEmit -p tsconfig.json 2>&1 | grep -E "rmharks/image|storage/(keys|s3)" || echo "no type errors in new files"
Expected: prints no type errors in new files.
Step 7: Commit
git add app/routes/api/rmharks/image.ts lib/slice-it/upload-validation.ts lib/__tests__/detect-image-ext.test.ts
git commit -m "feat(feed): POST /api/rmharks/image upload route -> MinIO"
Task 6: Feed image serve route (app-proxied read)¶
Files:
Create:
app/routes/api/feed/image/$filename.ts
Interfaces:
Consumes:
getObject(Task 2);feedImageKey,isSafeFilename,contentTypeForFilename(Task 1).Produces:
GET /api/feed/image/<filename>→ streams the object with long-lived immutable cache headers, 404 when missing/unsafe.Step 1: Create the serve route (mirrors
app/routes/api/profile/avatar/$filename.ts)
// app/routes/api/feed/image/$filename.ts
import { createFileRoute } from '@tanstack/react-router';
import { getObject } from "@/lib/storage/s3.server";
import { feedImageKey, isSafeFilename, contentTypeForFilename } from "@/lib/storage/keys";
export const Route = createFileRoute('/api/feed/image/$filename')({
server: {
handlers: {
GET: async ({ params }) => {
try {
const { filename } = params;
if (!isSafeFilename(filename)) {
return new Response("Not Found", { status: 404 });
}
const object = await getObject(feedImageKey(filename));
if (!object) {
return new Response("Not Found", { status: 404 });
}
return new Response(object.body, {
headers: {
"Content-Type": object.contentType || contentTypeForFilename(filename),
"Cache-Control": "public, max-age=31536000, immutable",
},
});
} catch (error) {
console.error("Feed image serve error:", error);
return new Response("Not Found", { status: 404 });
}
},
},
},
});
Step 2: Typecheck
Run: pnpm exec tsc --noEmit -p tsconfig.json 2>&1 | grep -E "feed/image" || echo "no type errors in serve route"
Expected: prints no type errors in serve route.
Step 3: Manual end-to-end verification (requires MinIO running)
Run, with the dev stack up (docker compose up -d minio minio-init and pnpm run dev):
# Upload (replace COOKIE with a logged-in session cookie and ./pic.png with a real PNG)
curl -s -b "$COOKIE" -F "images=@./pic.png" http://localhost:7005/api/rmharks/image
# -> {"urls":["/api/feed/image/<id>.png"]}
# Then fetch the returned URL and confirm 200 + image/png:
curl -s -o /dev/null -w "%{http_code} %{content_type}\n" http://localhost:7005/api/feed/image/<id>.png
Expected: upload returns a urls array; the GET prints 200 image/png.
Step 4: Commit
git add app/routes/api/feed/image/\$filename.ts
git commit -m "feat(feed): GET /api/feed/image/:filename serve route (app-proxied)"
Task 7: Persist + return imageUrls in the RMHark create/read route¶
Files:
Modify:
app/routes/api/rmharks.ts(POST handler ~line 470+, GET handler item mappers)
Interfaces:
Consumes:
createRMHarkSchema.imageUrls(Task 4);RMHark.imageUrlscolumn (Task 4).Produces: created/fetched
FeedItems carryimageUrls.Step 1: Persist
imageUrlson create
In the POST handler, change the destructure and the tx.rMHark.create data:
const { content, poll, gifUrl, imageUrls } = parsed.data;
const created = await tx.rMHark.create({
data: {
content: content.trim(),
gifUrl: gifUrl ?? null,
imageUrls: imageUrls ?? [],
userId: session.user.id,
},
include: {
user: { select: userDisplaySelect },
},
});
Step 2: Return
imageUrlsin the createdFeedItem
In the POST handler’s const item: FeedItem = { ... }, add after gifUrl: rmhark.gifUrl ?? undefined,:
imageUrls: rmhark.imageUrls,
Step 3: Return
imageUrlsfrom the GET mappers
In app/routes/api/rmharks.ts there are four FeedItem mappers building ownItems/repostItems (in both the friends branch and the default branch). In each, immediately after the existing gifUrl: isDeleted ? undefined : (r.gifUrl ?? undefined), line, add:
imageUrls: isDeleted ? undefined : r.imageUrls,
(There are exactly four occurrences of that gifUrl: line in the file — add the imageUrls line after each.)
Step 4: Typecheck
Run: pnpm exec tsc --noEmit -p tsconfig.json 2>&1 | grep -E "api/rmharks.ts" || echo "no type errors in rmharks route"
Expected: prints no type errors in rmharks route.
Step 5: Verify the existing suite still passes
Run: node_modules/.bin/vitest run
Expected: PASS (all suites green, including the new storage/schema tests).
Step 6: Commit
git add app/routes/api/rmharks.ts
git commit -m "feat(feed): persist and return imageUrls on RMHark create/read"
Task 8: Composer UI — attach/preview images; render images in the feed¶
Files:
Modify: the RMHark composer component and the feed-item renderer (locate both before editing — see Step 1)
Interfaces:
Consumes:
POST /api/rmharks/image(Task 5);FeedItem.imageUrls(Task 4); the existing create-post call toPOST /api/rmharks.Step 1: Locate the composer and renderer
Run:
grep -rln "gifUrl" app/components app/routes | grep -v "api/"
Expected: the files that read/write gifUrl on the client — the composer (where a GIF is attached before posting) and the feed item renderer (where gifUrl is displayed). Edit those same files. If multiple, the composer is the one issuing fetch("/api/rmharks", { method: "POST" }); the renderer is the one rendering item.gifUrl inside the feed card.
Step 2: Add an image picker + upload to the composer
In the composer, mirror the existing GIF-attach UX. Add local state and an upload handler that posts selected files to /api/rmharks/image and stores the returned URLs:
const [imageUrls, setImageUrls] = useState<string[]>([]);
async function handleImageFiles(files: FileList | null) {
if (!files || files.length === 0) return;
const remaining = 4 - imageUrls.length;
const form = new FormData();
Array.from(files).slice(0, remaining).forEach((f) => form.append("images", f));
const res = await fetch("/api/rmharks/image", { method: "POST", body: form });
if (!res.ok) {
const { error } = await res.json().catch(() => ({ error: "Upload failed" }));
// surface `error` via the composer's existing error toast/state
return;
}
const { urls } = await res.json();
setImageUrls((prev) => [...prev, ...urls].slice(0, 4));
}
Add a hidden file input (accept="image/png,image/jpeg,image/gif,image/webp" multiple) triggered by an image button next to the existing GIF button, a thumbnail preview strip for imageUrls with a remove control (setImageUrls(prev => prev.filter(u => u !== url))), and disable the image button once imageUrls.length >= 4.
Step 3: Include
imageUrlsin the create-post request
In the composer’s submit handler, add imageUrls to the JSON body sent to POST /api/rmharks (only when non-empty), and clear it (setImageUrls([])) on success alongside the existing content/gif reset:
body: JSON.stringify({
content,
...(gifUrl ? { gifUrl } : {}),
...(imageUrls.length ? { imageUrls } : {}),
...(poll ? { poll } : {}),
}),
Step 4: Render
imageUrlsin the feed item
In the feed-item renderer, near where item.gifUrl is rendered, render the image grid when item.imageUrls?.length:
{item.imageUrls && item.imageUrls.length > 0 && (
<div className={`mt-2 grid gap-1 ${item.imageUrls.length === 1 ? "grid-cols-1" : "grid-cols-2"}`}>
{item.imageUrls.map((url) => (
<img
key={url}
src={url}
alt=""
loading="lazy"
className="w-full rounded-lg object-cover max-h-80"
/>
))}
</div>
)}
Step 5: Typecheck + lint the changed files
Run: pnpm exec tsc --noEmit -p tsconfig.json 2>&1 | tail -5 ; pnpm run lint 2>&1 | tail -5
Expected: no new type errors; lint clean on the edited files.
Step 6: Manual verification (dev stack up)
With docker compose up -d minio minio-init and pnpm run dev: open the feed, attach 1–4 images to a new post, submit, and confirm the post renders with the images and that a hard refresh still shows them (served via /api/feed/image/...). Confirm a 5th image is blocked client-side and the server rejects >4 / >5 MB.
Step 7: Commit
git add app/components app/routes
git commit -m "feat(feed): attach, preview, and render images on RMHark posts"
Self-Review¶
Spec coverage:
MinIO now / R2-ready seam → Tasks 2 (wrapper), 3 (env
S3_FORCE_PATH_STYLE, docs). ✓Storage module as the only provider seam → Task 2 (Global Constraint enforces it). ✓
Env/config (
S3_*) in.env.example, compose, helm → Task 3. ✓MinIO deployment (compose + helm) → Task 3. ✓
Upload route mirroring avatar (auth, rate-limit, 5 MB cap,
validateImageBuffer, key format) → Task 5. ✓Read route (public, app-proxied, immutable cache, 404) → Task 6. ✓
imageUrls String[]on RMHark + migration + create wiring + composer/render → Tasks 4, 7, 8. ✓Up to 4 images, 5 MB each → Tasks 4 (schema), 5 (route), 8 (UI). ✓
Deferred deleted-post cleanup → stated out-of-scope in Global Constraints. ✓
Tests for storage module + schema → Tasks 1, 2, 4, 5. ✓
Placeholder scan: No TBD/TODO; every code step has full code. Task 8 intentionally locates the composer/renderer at execution time (Step 1) because those component paths weren’t enumerated during planning — the grep command and identifying criteria are explicit, so this is actionable, not a placeholder.
Type consistency: getObject returns { body: Buffer; contentType: string } | null and is consumed that way in Task 6. feedImageKey/feedImageUrl/isSafeFilename/contentTypeForFilename signatures match across Tasks 1, 5, 6. imageUrls is string[] in Prisma, string[] | undefined in FeedItem, and persisted as imageUrls ?? [] in Task 7 — consistent. detectImageExt return union matches its use in Task 5.
Note on route testing: This repo has no HTTP route test harness (Vitest include globs cover only lib//testing/ node units). Per existing convention, route correctness is covered by (a) unit-testing the extracted helpers (storage-keys, storage-s3, rmhark-schema, detect-image-ext) and (b) explicit manual curl/browser verification steps. This is a deliberate match to the codebase, not an omission.