mv-s3-manager/fastify

Plugin Fastify per la gestione di bucket S3-compatibili.

Decora la tua istanza Fastify con fastify.s3 e registra opzionalmente le route di upload, download, listaggio, eliminazione e URL prefirmati.

Installazione

npm install mv-s3-manager/fastify mv-s3-manager/core fastify @fastify/multipart
# oppure
pnpm add mv-s3-manager/fastify mv-s3-manager/core fastify @fastify/multipart

Avvio rapido

import Fastify from "fastify";
import { s3ManagerPlugin } from "mv-s3-manager/fastify";

const fastify = Fastify({ logger: true });

await fastify.register(s3ManagerPlugin, {
  config: {
    region: "us-east-1",
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    },
    bucket: "mio-bucket",
  },
  // prefix: "/s3" (default) — registra le route sotto /s3/*
  // prefix: false — solo decorator, nessuna route registrata
});

// Usa il decorator nelle tue route:
fastify.get("/files", async () => {
  return fastify.s3.list({ prefix: "upload/" });
});

await fastify.listen({ port: 3000 });

Opzioni del plugin

| Opzione | Tipo | Default | Descrizione | |---|---|---|---| | config | S3ManagerConfig | obbligatorio | Configurazione del bucket S3-compatibile | | prefix | string \| false | "/s3" | Prefisso URL per le route auto-registrate. false disabilita la registrazione delle route. | | registerMultipart | boolean | true | Registra automaticamente @fastify/multipart. Imposta false se già registrato. |

Route auto-registrate

Quando prefix è impostato (default "/s3"), vengono registrate le seguenti route:

| Metodo | Percorso | Descrizione | |---|---|---| | POST | {prefix}/upload?key=<chiave> | Carica un file (multipart/form-data, campo "file") | | GET | {prefix}/download/* | Scarica un oggetto tramite chiave | | GET | {prefix}/list | Elenca gli oggetti (?prefix=, ?maxKeys=, ?continuationToken=) | | DELETE | {prefix}/delete/* | Elimina un oggetto tramite chiave | | GET | {prefix}/presigned/download/* | Ottieni URL prefirmato di download (?expiresIn=) | | GET | {prefix}/presigned/upload/* | Ottieni URL prefirmato di upload (?expiresIn=, ?contentType=) |

API del decorator fastify.s3

Dopo la registrazione, fastify.s3 espone:

fastify.s3.upload(key, body, options?)         // → Promise<UploadResult>
fastify.s3.download(key)                        // → Promise<DownloadResult>
fastify.s3.delete(key)                          // → Promise<void>
fastify.s3.deleteMany(keys)                     // → Promise<string[]>
fastify.s3.list(options?)                       // → Promise<ListResult>
fastify.s3.listAll(options?)                    // → AsyncGenerator<S3Object>
fastify.s3.presignedDownload(key, options?)     // → Promise<string>
fastify.s3.presignedUpload(key, options?)       // → Promise<string>
fastify.s3.client                               // istanza S3Client
fastify.s3.config                               // S3ManagerConfig risolta

Modalità solo-decorator

await fastify.register(s3ManagerPlugin, { config, prefix: false });

// Nessuna route registrata — usa il decorator nei tuoi gestori:
fastify.post("/avatar", async (req, reply) => {
  const file = await req.file();
  const chunks: Buffer[] = [];
  for await (const chunk of file.file) chunks.push(chunk as Buffer);
  const result = await fastify.s3.upload(`avatar/${req.user.id}.jpg`, Buffer.concat(chunks));
  return result;
});