Stockages

colis parle S3. Tout stockage compatible convient ; le point d’accès (endpoint) est la seule différence. Quand il est défini, deux valeurs par défaut suivent :

• region devient "auto", la convention des fournisseurs qui ignorent la région mais dont le SDK en exige une ;
• forcePathStyle devient true : https://endpoint/bucket/key plutôt que https://bucket.endpoint/key. Les passerelles auto-hébergées l’exigent, les fournisseurs gérés l’acceptent.

Les deux restent modifiables. Dans chaque cas, donnez aux clés la lecture et l’écriture sur ce seul bucket, rien d’autre : des clés capables de lister le bucket permettraient d’énumérer les codes.

Cloudflare R2

Pas de frais de sortie, ce qui compte quand vos clients téléchargent des fichiers lourds. Créez le bucket (R2 → Create bucket) et un jeton d’API Object Read & Write limité à ce bucket. L’identifiant de compte est le début du point d’accès S3 que R2 affiche.

Pour la page de livraison :

COLIS_BUCKET=livraisons
COLIS_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
COLIS_REGION=auto
AWS_ACCESS_KEY_ID=…
AWS_SECRET_ACCESS_KEY=…

Pour la CLI en mode bucket, colis init --provider r2 --bucket livraisons écrit le même réglage, avec les secrets lus depuis .env (R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY).

Dans votre code :

import { createBucket } from '@colis/core'

const store = createBucket({
  bucket: 'livraisons',
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
  },
})

Les règles de cycle de vie et CORS se règlent dans R2 → votre bucket → Settings. R2 abandonne de lui-même les envois multipart incomplets après sept jours.

AWS S3

Laissez COLIS_ENDPOINT vide et donnez une vraie région (COLIS_REGION=eu-west-3). Sans clés explicites, la chaîne d’identifiants d’AWS s’applique : variables AWS_*, profil partagé, rôle d’instance. Sur un hébergement qui fournit un rôle, préférez-le : rien à faire tourner, rien à fuiter.

La politique minimale pour le préfixe des colis :

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": "arn:aws:s3:::livraisons/*"
    }
  ]
}

Les deux dernières actions ne servent qu’aux gros fichiers. Signer une URL ne demande aucune permission de plus : c’est un calcul local sur les clés que vous détenez déjà.

colis verifier en mode bucket appelle aussi HeadBucket, qu’AWS autorise avec s3:ListBucket sur le bucket lui-même, et lit les règles de cycle de vie et CORS. Avec la politique ci-dessus, ces contrôles échouent ou avertissent alors que la page de livraison fonctionne : vérifiez plutôt le déploiement avec colis verifier --remote.

MinIO

Le moyen le plus rapide d’essayer le vrai chemin de code, sans compte :

docker run -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin -e MINIO_ROOT_PASSWORD=minioadmin \
  quay.io/minio/minio server /data --console-address ":9001"

Créez le bucket depuis la console sur localhost:9001, puis COLIS_ENDPOINT=http://localhost:9000 avec minioadmin / minioadmin comme clés. colis init --provider minio écrit le même réglage pour la CLI.

Scaleway Object Storage

Scaleway utilise vraiment la région : donnez-la plutôt que de laisser "auto".

COLIS_ENDPOINT=https://s3.fr-par.scw.cloud
COLIS_REGION=fr-par

colis init --provider scaleway lit les clés dans SCW_ACCESS_KEY et SCW_SECRET_KEY.

Wasabi

COLIS_ENDPOINT=https://s3.eu-central-1.wasabisys.com
COLIS_REGION=eu-central-1

colis init --provider wasabi lit les clés dans WASABI_ACCESS_KEY et WASABI_SECRET_KEY.

À propos des ACL

upload() accepte une option acl, mais la plupart des buckets récents ont les ACL désactivées, et R2 ne les prend pas en charge : l’option fait alors échouer la requête. colis n’a pas besoin d’objets publics ; laissez acl de côté.

Vérifier

Quel que soit le fournisseur, colis verifier en mode bucket effectue les opérations dont colis a besoin et signale la règle de cycle de vie ou la règle CORS manquante. Voir CLI.