# Créer un pipeline de livraison de médias

Téléchargez un MP4 dans un stockage S3 privé, reprenez après un redémarrage et donnez à votre application accès au fichier vérifié.

Référence canonique : https://flashdata.dev/fr/docs/guides/media-delivery-pipeline
Vérifié le 2026-11-05 par FlashData

<a id="prepare"></a>

## Ce que vous allez créer

Un élément conservé sur disque passe d’un identifiant vidéo à un fichier utilisable par l’application. Enregistrez chaque étape pour qu’un nouveau processus puisse reprendre au dernier résultat confirmé.

### Pipeline et enregistrements conservés

```text
item.json
  → soumettre une seule fois  → exécution et identifiant de tâche enregistrés
  → reprendre la tâche       → delivery.json
  → vérifier les octets S3   → media.mp4 + ready.json
  → autoriser l’utilisateur  → URL de téléchargement à durée limitée
```

- [Choisir l’audio, la vidéo ou un extrait](https://flashdata.dev/fr/docs/guides/youtube-download-guide/reference.md#formats)

<a id="requirements"></a>

### Avant de commencer

Choisissez une seule variante pour les six étapes. Toutes deux utilisent la CLI FlashData installée avec un profil propriétaire enregistré et la permission youtube_download, un fichier storage.json privé pour les transferts vers S3, et une identité AWS autorisée à lire l’objet livré.

#### Python

Utilisez Python 3.10+ dans votre environnement Python. Les scripts appellent la CLI pour conserver son journal d’exécution, et Boto3 pour lire S3 et signer les liens. Bash, jq, Node.js et AWS CLI ne sont pas nécessaires. Exécutez les commandes avec python, ou python3 si votre interpréteur porte ce nom.

##### Installer la dépendance Python

```bash
python --version
flashdata --version
python -m pip install boto3
```


#### Bash / Node.js

Installez Bash, jq, Node.js 22+ et AWS CLI v2. Sous Windows, exécutez les commandes Bash dans Git Bash. Les paquets Node de signature S3 seront installés à l’étape 6.


- [Premier téléchargement](https://flashdata.dev/fr/docs/guides/download-video-recipe/reference.md)
- [Configurer un fichier storage.json privé](https://flashdata.dev/fr/docs/guides/cli-automation/reference.md#storage)
- [Profils enregistrés](https://flashdata.dev/fr/docs/guides/cli-automation/reference.md#profiles)
- [Identifiants AWS pour Boto3](https://docs.aws.amazon.com/boto3/latest/guide/credentials.html)

<a id="environment"></a>

### Enregistrer les paramètres d’exécution

Créez un dossier privé pour cet élément, hors du dépôt de code. Enregistrez les paramètres de la variante choisie et adaptez les chemins absolus et le nom du profil. Chaque processus utilise le compte et le journal d’exécution enregistrés. Les identifiants de stockage restent dans le fichier privé storage.json. Exécutez un seul processus par élément à la fois.

#### Python

Enregistrez pipeline.json. Sous Windows, les chemins avec des barres obliques, comme C:/private/flashdata-state, fonctionnent en JSON.

##### pipeline.json

```json
{
  "stateDir": "/absolute/path/to/flashdata-state",
  "storageConfig": "/absolute/path/to/private/storage.json",
  "profile": "default"
}
```


#### Bash

##### pipeline.env

```bash
# pipeline.env — edit these paths for your existing installation.
export FLASHDATA_STATE_DIR='/absolute/path/to/flashdata-state'
export FLASHDATA_STORAGE_CONFIG='/absolute/path/to/private/storage.json'
export FLASHDATA_PROFILE='default'
# Use the saved profile for every process.
unset FLASHDATA_API_KEY
```



<a id="design"></a>

## 1. Enregistrer un élément à traiter

Enregistrez item.json dans ce dossier. Remplacez la vidéo et la destination S3 ; cet exemple demande un MP4 limité à 720p. Conservez son runId pour les nouvelles tentatives. Une sortie différente nécessite un nouveau runId et un nouveau préfixe d’objet.

### item.json

```json
{
  "runId": "media:clip-001:720p:v1",
  "request": {
    "source": "youtube_download",
    "video_id": "jNQXAC9IVRw",
    "params": {
      "download_type": "audio_video",
      "video_quality": "<=720",
      "output_format": "mp4"
    }
  },
  "destination": {
    "bucket": "your-media-bucket",
    "region": "us-east-1",
    "prefix": "media/clip-001-v1"
  }
}
```


<a id="check"></a>

## 2. Enregistrer le script et vérifier l’accès

Créez le fichier ci-dessous avant de lancer les vérifications. Il valide la destination S3 et conserve un reçu pour chaque tentative de soumission.


<a id="request-script"></a>

### Créer le script du pipeline

#### Python

Créez pipeline.py dans le même dossier que pipeline.json et item.json. Copiez-y le code complet ci-dessous et enregistrez-le. Vous le réutiliserez pour les vérifications, la soumission et la reprise aux étapes 2 à 4.

##### pipeline.py

```python
# pipeline.py — Python 3.10+ and the FlashData CLI on PATH.
import argparse
import json
import os
import subprocess
import sys
import tempfile
from pathlib import Path

ROOT = Path(__file__).resolve().parent


def read_json(path):
    return json.loads(Path(path).read_text(encoding='utf-8-sig'))


def delivery_directory():
    # Recovery updates this pointer only after the delivery is saved successfully.
    return ROOT / (ROOT / 'delivery-dir.txt').read_text(encoding='utf-8').strip()


def main(action):
    os.umask(0o077)
    settings = read_json(ROOT / 'pipeline.json')
    for name in ['stateDir', 'storageConfig']:
        if not Path(settings[name]).is_absolute():
            raise ValueError('Set an absolute path for ' + name)
    item = read_json(ROOT / 'item.json')
    run_id = item['runId']
    env = dict(os.environ)
    env.pop('FLASHDATA_API_KEY', None)  # Reuse the saved owner profile.
    flags = ['--profile', settings['profile'], '--state-dir', settings['stateDir'],
             '--json', '--non-interactive']

    def cli(*args, payload=None, attempt=None):
        result = subprocess.run(['flashdata', *args, *flags], cwd=ROOT, env=env,
                                input=json.dumps(payload) if payload is not None else None,
                                capture_output=True, text=True, encoding='utf-8')
        if attempt:
            (attempt / 'receipt.json').write_text(result.stdout, encoding='utf-8')
            (attempt / 'error.json').write_text(result.stderr, encoding='utf-8')
        if result.returncode:
            if attempt:
                raise RuntimeError('Keep ' + str(attempt) + '; inspect its error and saved run.')
            raise RuntimeError(result.stderr.strip() or 'FlashData command failed.')
        response = json.loads(result.stdout)
        if not response.get('ok'):
            raise RuntimeError('Inspect the CLI response before continuing.')
        return response

    def new_attempt(stage):
        attempts = ROOT / 'attempts'
        attempts.mkdir(exist_ok=True)
        return Path(tempfile.mkdtemp(prefix=stage + '.', dir=attempts))

    if action == 'check':
        access = cli('auth', 'status')['data']
        identity = access['identity']
        if (not access.get('accessVerified')
                or identity['identity'].get('recurringAllowed') is not True
                or 'youtube_download' not in identity.get('permittedSources', [])):
            raise ValueError('Owner access with youtube_download is required.')
        print(json.dumps({'accountId': identity['identity']['accountId'],
                          'permittedSources': identity['permittedSources']}, indent=2))
        for args in [('account', 'balance'),
                     ('account', 'pricing', '--source', 'youtube_download', '--request-count', '1'),
                     ('account', 'limits')]:
            print(json.dumps(cli(*args)['data'], indent=2))
    elif action in ['dry-run', 'submit']:
        storage = read_json(settings['storageConfig'])
        destination = item['destination']
        if (item['request']['source'] != 'youtube_download'
                or storage.get('storage_type') != 's3'
                or storage.get('storage_url') != destination['bucket']
                or storage.get('region') != destination['region']):
            raise ValueError('Check item.json and the S3 destination in storage.json.')
        request = item['request']
        request['params']['storage'] = {**storage, 'object_prefix': destination['prefix']}
        args = ['query', '--input', '-', '--mode', 'async', '--run-id', run_id]
        if action == 'dry-run':
            response = cli(*args, '--dry-run', payload=request)
            if response['data'].get('dryRun') is not True:
                raise ValueError('Expected a dry-run result.')
            print(json.dumps({'ok': True, 'dryRun': True}))
        else:
            attempt = new_attempt('submit')
            response = cli(*args, '--output', str(attempt / 'submission.json'),
                           payload=request, attempt=attempt)
            print(json.dumps({'runId': run_id, 'cached': response.get('cached'),
                              'receipt': str(attempt / 'submission.json')}, indent=2))
    elif action == 'inspect':
        run = cli('runs', 'show', run_id)['data']
        print(json.dumps({'runId': run_id, 'status': run['status'], 'jobId': run.get('remoteId'),
                          'errorCode': run.get('errorCode'),
                          'candidateJobIds': run.get('candidateRemoteIds')}, indent=2))
    elif action == 'recover':
        attempt = new_attempt('recover')
        cli('runs', 'recover', run_id, '--timeout', '10m',
            '--output', str(attempt / 'delivery.json'), attempt=attempt)
        run = cli('runs', 'show', run_id)
        (attempt / 'run.json').write_text(json.dumps(run, indent=2), encoding='utf-8')
        delivery = read_json(attempt / 'delivery.json')
        if delivery.get('source') != 'youtube_download' or delivery.get('status') != 'done':
            raise ValueError('Inspect the saved delivery before verifying.')
        pointer = ROOT / 'delivery-dir.next'
        pointer.write_text(attempt.relative_to(ROOT).as_posix(), encoding='utf-8')
        pointer.replace(ROOT / 'delivery-dir.txt')
        print('Delivery files:', attempt)
    elif action == 'delivery':
        delivery = read_json(delivery_directory() / 'delivery.json')
        print(json.dumps({'status': delivery['status'], 'file': delivery['results'][0],
                          'usage': delivery.get('usage')}, indent=2))


if __name__ == '__main__':
    sys.stdout.reconfigure(encoding='utf-8')
    sys.stderr.reconfigure(encoding='utf-8')
    parser = argparse.ArgumentParser()
    parser.add_argument('action', choices=['check', 'dry-run', 'submit', 'inspect', 'recover', 'delivery'])
    try:
        main(parser.parse_args().action)
    except (OSError, ValueError, KeyError, RuntimeError) as error:
        print(str(error), file=sys.stderr)
        sys.exit(1)
```


#### Bash

Créez request-media.sh dans le même dossier que pipeline.env et item.json. Copiez-y le code complet ci-dessous et enregistrez-le.

##### request-media.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
umask 077
cd -- "$(dirname -- "$0")"
. ./pipeline.env
: "${FLASHDATA_STATE_DIR:?Set your existing absolute CLI state directory}"
: "${FLASHDATA_STORAGE_CONFIG:?Set the absolute path to private storage.json}"
action=${1:-dry-run}
[[ "$action" == dry-run || "$action" == submit ]] || exit 2
run_id=$(jq -er '.runId | select(type == "string" and length > 0)' item.json)
request() {
  jq -en --slurpfile item item.json --slurpfile storage "$FLASHDATA_STORAGE_CONFIG" '
    $item[0] as $i | $storage[0] as $s
    | if $i.request.source != "youtube_download"
        or $s.storage_type != "s3" or $s.storage_url != $i.destination.bucket
        or $s.region != $i.destination.region
      then error("Check item.json and the S3 destination in storage.json")
      else $i.request | .params.storage = ($s + {object_prefix: $i.destination.prefix}) end'
}
args=(query --input - --mode async --run-id "$run_id"
  --profile "${FLASHDATA_PROFILE:-default}" --state-dir "$FLASHDATA_STATE_DIR"
  --json --non-interactive)
if [[ "$action" == dry-run ]]; then
  request | flashdata "${args[@]}" --dry-run
else
  mkdir -p attempts
  attempt=$(mktemp -d attempts/submit.XXXXXX)
  if ! request | flashdata "${args[@]}" --output "$attempt/submission.json" \
    > "$attempt/receipt.json" 2> "$attempt/error.json"; then
    cat "$attempt/error.json" >&2
    printf 'Keep %s; inspect the saved run before retrying.\n' "$attempt" >&2
    exit 1
  fi
  jq '{runId, cached, data}' "$attempt/receipt.json"
  printf 'Saved receipt: %s/submission.json\n' "$attempt"
fi
```



<a id="access-check"></a>

### Vérifier le compte enregistré

Lancez cette vérification gratuite depuis le dossier de l’élément après avoir enregistré le script. L’absence d’accès propriétaire ou de permission youtube_download interrompt la vérification. Confirmez l’identifiant du compte, le solde, le tarif par téraoctet et les limites. Le coût final dépend des octets transférés vers le stockage.

#### Python

##### Vérifier l’environnement et le compte

```bash
python pipeline.py check
```


#### Bash

##### Vérifier l’environnement et le compte

```bash
set -euo pipefail
. ./pipeline.env
: "${FLASHDATA_STATE_DIR:?Set your existing absolute CLI state directory}"
: "${FLASHDATA_STORAGE_CONFIG:?Set the absolute path to private storage.json}"
flashdata --version
jq --version
node --version
aws --version
flashdata auth status --profile "${FLASHDATA_PROFILE:-default}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive |
  jq -e 'if .ok and .data.accessVerified
    and (.data.identity.identity.recurringAllowed == true)
    and (.data.identity.permittedSources | index("youtube_download") != null)
    then {accountId: .data.identity.identity.accountId,
          permittedSources: .data.identity.permittedSources}
    else error("Owner access with youtube_download is required.") end'
flashdata account balance --profile "${FLASHDATA_PROFILE:-default}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
flashdata account pricing --source youtube_download --request-count 1 \
  --profile "${FLASHDATA_PROFILE:-default}" --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
flashdata account limits --profile "${FLASHDATA_PROFILE:-default}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive
```


- [Revenir au code du script](https://flashdata.dev/fr/docs/guides/media-delivery-pipeline/reference.md#request-script)

<a id="dry-run"></a>

### Valider sans télécharger

Après avoir enregistré le script, lancez sa simulation. Python affiche ok: true et dryRun: true ; Bash affiche true. Cela valide les paramètres et l’accès sans soumettre de téléchargement ni réserver de crédits.

#### Python

##### Simulation gratuite

```bash
python pipeline.py dry-run
```


#### Bash

##### Simulation gratuite

```bash
set -euo pipefail
bash request-media.sh dry-run | jq -e '.ok and .data.dryRun'
```



<a id="dispatch"></a>

## 3. Soumettre et conserver l’identifiant de tâche

Cette commande soumet un téléchargement payant en arrière-plan. L’exécution locale doit indiquer status: accepted et un jobId. Conservez le profil, le répertoire d’état et item.json pour la reprise. Le média n’est prêt qu’après l’étape 5.

### Python

#### Soumettre une seule fois

```bash
python pipeline.py submit
```

#### Examiner l’état local · aucune nouvelle requête

```bash
python pipeline.py inspect
```


### Bash

#### Soumettre une seule fois

```bash
bash request-media.sh submit
```

#### Examiner l’état local · aucune nouvelle requête

```bash
set -euo pipefail
. ./pipeline.env
RUN_ID=$(jq -er '.runId' item.json)
flashdata runs show "$RUN_ID" --profile "${FLASHDATA_PROFILE:-default}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive |
  jq '{runId, status: .data.status, jobId: .data.remoteId,
       errorCode: .data.errorCode, candidateJobIds: .data.candidateRemoteIds}'
```



<a id="job-state"></a>

### Si l’exécution est déjà enregistrée ou incertaine

| État CLI | Action |
| --- | --- |
| accepted + jobId | Reprenez cette exécution à l’étape 4. Conservez l’identifiant de tâche si le processus s’arrête. |
| succeeded | Récupérez ou exportez la réponse enregistrée, puis vérifiez le stockage. Ne soumettez pas de nouvel élément. |
| Résultat inconnu / aucun identifiant de tâche confirmé | Conservez l’exécution, le reçu et l’erreur. Consultez History ou les identifiants possibles avant de décider d’une nouvelle soumission. |

- [Historique des requêtes](https://flashdata.dev/app/jobs)
- [Reprendre une soumission incertaine](https://flashdata.dev/fr/docs/guides/agent-recovery/reference.md)

<a id="recover"></a>

## 4. Récupérer le résultat de livraison

Lancez la commande depuis le dossier de l’élément dans un nouveau terminal. La reprise attend la tâche d’origine et affiche un répertoire contenant delivery.json, run.json et les reçus. Après 10 minutes, le délai d’attente local expire ; relancez la reprise pour suivre la même tâche.


<a id="recovery-script"></a>

### Reprendre la tâche enregistrée

#### Python

Réutilisez pipeline.py enregistré à l’étape 2. Aucun script supplémentaire n’est nécessaire.

##### Reprendre la tâche existante · aucune nouvelle soumission

```bash
python pipeline.py recover
```


#### Bash

Créez d’abord recover-media.sh à côté de item.json et copiez-y le code ci-dessous. Enregistrez le fichier, puis exécutez la commande de reprise placée après le script.

##### recover-media.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
umask 077
cd -- "$(dirname -- "$0")"
. ./pipeline.env
: "${FLASHDATA_STATE_DIR:?Set your existing absolute CLI state directory}"
RUN_ID=$(jq -er '.runId' item.json)
mkdir -p attempts
DELIVERY_DIR=$(mktemp -d attempts/recover.XXXXXX)
if ! flashdata runs recover "$RUN_ID" --timeout 10m \
  --profile "${FLASHDATA_PROFILE:-default}" --state-dir "$FLASHDATA_STATE_DIR" \
  --output "$DELIVERY_DIR/delivery.json" --json --non-interactive \
  > "$DELIVERY_DIR/receipt.json" 2> "$DELIVERY_DIR/error.json"; then
  cat "$DELIVERY_DIR/error.json" >&2
  printf 'Keep %s; recover the same run after resolving the error.\n' "$DELIVERY_DIR" >&2
  exit 1
fi
flashdata runs show "$RUN_ID" --profile "${FLASHDATA_PROFILE:-default}" \
  --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive > "$DELIVERY_DIR/run.json"
jq -e '.source == "youtube_download" and .status == "done"' \
  "$DELIVERY_DIR/delivery.json" >/dev/null
printf '%s\n' "$DELIVERY_DIR"
```

##### Reprendre la tâche existante · aucune nouvelle soumission

```bash
set -euo pipefail
DELIVERY_DIR=$(bash recover-media.sh)
printf 'Delivery files: %s\n' "$DELIVERY_DIR"
```



<a id="delivery-record"></a>

### Examiner l’objet livré

Le résultat attendu contient une URL d’objet S3, une taille positive et un MD5. Les objets privés nécessitent votre identité AWS autorisée en lecture. Python enregistre le répertoire du résultat réussi dans delivery-dir.txt pour les scripts suivants. Bash conserve DELIVERY_DIR ; dans un nouveau terminal, définissez cette variable avec le répertoire affiché.

#### Python

##### Résultat de livraison

```bash
python pipeline.py delivery
```


#### Bash

##### Résultat de livraison

```bash
jq '{status, file: .results[0], usage}' "$DELIVERY_DIR/delivery.json"
```



<a id="verify"></a>

## 5. Vérifier les octets avant de déclarer le fichier prêt

Le script vérifie les paramètres d’origine, le bucket et le préfixe S3, écrit progressivement l’objet privé sur disque, puis compare sa taille en octets et son MD5. Seuls les fichiers conformes produisent verified/ready.json. Python lit delivery-dir.txt ; Node utilise DELIVERY_DIR. Aucun des deux ne soumet de requête FlashData.


<a id="verify-script"></a>

### Enregistrer le script de vérification

Ce script traite les URL d’objets Amazon S3 standard. Pour un endpoint personnalisé ou un autre fournisseur, utilisez sa lecture authentifiée d’objets en conservant les vérifications de destination, de taille et de somme de contrôle.

#### Python

Créez verify-media.py à côté de pipeline.py et copiez-y le code complet ci-dessous. Enregistrez les deux fichiers dans le dossier de l’élément.

##### verify-media.py

```python
# verify-media.py — uses Boto3's configured AWS read identity.
import hashlib
import json
import os
import re
import sys
from contextlib import closing
from datetime import datetime, timezone
from urllib.parse import unquote, urlsplit

import boto3
from pipeline import ROOT, delivery_directory, read_json


def main():
    os.umask(0o077)
    directory = delivery_directory()
    item = read_json(ROOT / 'item.json')
    saved = read_json(directory / 'run.json')
    raw = (directory / 'delivery.json').read_bytes()
    delivery = json.loads(raw)
    run = saved.get('data', {})
    if (not saved.get('ok') or run.get('id') != item['runId']
            or run.get('status') != 'succeeded' or not run.get('remoteId')
            or delivery.get('source') != 'youtube_download' or delivery.get('status') != 'done'
            or not isinstance(delivery.get('results'), list) or len(delivery['results']) != 1):
        raise ValueError('Inspect the saved run and completed delivery before verifying.')
    file = delivery['results'][0]
    bucket, region, prefix = (item['destination'][key] for key in ['bucket', 'region', 'prefix'])
    original = run.get('input', {})
    storage = original.get('params', {}).get('storage', {})
    if (original.get('source') != 'youtube_download' or original.get('video_id') != item['request']['video_id']
            or any(original.get('params', {}).get(key) != item['request']['params'][key]
                   for key in ['download_type', 'video_quality', 'output_format'])
            or storage.get('storage_url') != bucket or storage.get('region') != region
            or storage.get('object_prefix') != prefix):
        raise ValueError('item.json changed after submission. Inspect the original run.')
    url = urlsplit(file['file_url'])
    hosts = [bucket + '.s3.' + region + '.amazonaws.com', bucket + '.s3.amazonaws.com']
    key = unquote(url.path[1:], errors='strict')
    if (url.scheme != 'https' or url.netloc not in hosts or url.query or url.fragment
            or not prefix or not key.startswith(prefix + '/')):
        raise ValueError('The delivery does not match the planned Amazon S3 destination.')
    if (type(file.get('file_size')) is not int or file['file_size'] <= 0
            or not re.fullmatch(r'[a-fA-F0-9]{32}', file.get('md5', ''))):
        raise ValueError('A positive file_size and MD5 are required. Keep the manifest.')
    verification = directory / 'verified'
    verification.mkdir(mode=0o700)  # Stop if an earlier verification already exists.
    local_file = verification / 'media.mp4'
    s3 = boto3.client('s3', region_name=region)
    response = s3.get_object(Bucket=bucket, Key=key)
    size, digest = 0, hashlib.md5(usedforsecurity=False)
    with closing(response['Body']) as stream, local_file.open('xb') as output:
        while chunk := stream.read(1024 * 1024):
            output.write(chunk)
            size += len(chunk)
            digest.update(chunk)
    md5 = digest.hexdigest()
    if size != file['file_size'] or md5 != file['md5'].lower():
        raise ValueError('Byte count or MD5 mismatch. Keep the file; do not mark it ready.')
    ready = {'runId': item['runId'], 'jobId': run['remoteId'], 'videoId': item['request']['video_id'],
             'bucket': bucket, 'region': region, 'objectKey': key,
             'storageVersionId': response.get('VersionId'), 'bytes': size, 'md5': md5,
             'verifiedAt': datetime.now(timezone.utc).isoformat(), 'localFile': str(local_file.resolve()),
             'deliverySha256': hashlib.sha256(raw).hexdigest(), 'usage': delivery.get('usage')}
    with (verification / 'ready.json').open('x', encoding='utf-8') as output:
        json.dump(ready, output, indent=2)
    print('Delivery verified:', verification / 'ready.json')
    print(json.dumps(ready, indent=2))


if __name__ == '__main__':
    sys.stdout.reconfigure(encoding='utf-8')
    sys.stderr.reconfigure(encoding='utf-8')
    try:
        main()
    except Exception as error:
        print(str(error), file=sys.stderr)
        sys.exit(1)
```


#### Node.js

Créez verify-media.mjs à côté de item.json et copiez-y le code complet ci-dessous.

##### verify-media.mjs

```javascript
import { readFile, mkdir, writeFile } from 'node:fs/promises';
import { createReadStream } from 'node:fs';
import { createHash } from 'node:crypto';
import { execFileSync } from 'node:child_process';
import { resolve, join } from 'node:path';

try {
  const directory = process.argv[2];
  if (!directory) throw new Error('Pass the directory printed by the recovery step.');
  const readJson = async path => JSON.parse(await readFile(path, 'utf8'));
  const item = await readJson('item.json');
  const run = await readJson(join(directory, 'run.json'));
  const raw = await readFile(join(directory, 'delivery.json'));
  const delivery = JSON.parse(raw);
  if (!run.ok || run.data?.id !== item.runId || run.data?.status !== 'succeeded'
      || !run.data?.remoteId || delivery.source !== 'youtube_download'
      || delivery.status !== 'done' || delivery.results?.length !== 1) {
    throw new Error('Inspect the saved run and completed delivery before verifying.');
  }
  const file = delivery.results[0];
  const { bucket, region, prefix } = item.destination;
  const input = run.data.input;
  const storage = input?.params?.storage;
  if (input?.source !== 'youtube_download' || input.video_id !== item.request.video_id
      || ['download_type', 'video_quality', 'output_format'].some(
        key => input.params?.[key] !== item.request.params[key])
      || storage?.storage_url !== bucket || storage.region !== region
      || storage.object_prefix !== prefix) {
    throw new Error('item.json changed after submission. Inspect the original run.');
  }
  const url = new URL(file.file_url);
  const hosts = [bucket + '.s3.' + region + '.amazonaws.com', bucket + '.s3.amazonaws.com'];
  const objectKey = decodeURIComponent(url.pathname.slice(1));
  if (url.protocol !== 'https:' || !hosts.includes(url.host) || url.username
      || url.password || url.search || url.hash || !prefix
      || !objectKey.startsWith(prefix + '/')) {
    throw new Error('The delivery does not match the planned Amazon S3 destination.');
  }
  if (!Number.isSafeInteger(file.file_size) || file.file_size <= 0
      || !/^[a-f0-9]{32}$/i.test(file.md5 ?? '')) {
    throw new Error('A positive file_size and MD5 are required. Keep the manifest.');
  }
  const verification = join(directory, 'verified');
  await mkdir(verification, { mode: 0o700 }); // Existing attempt: stop without overwriting.
  const localFile = join(verification, 'media.mp4');
  let metadata;
  try {
    metadata = JSON.parse(execFileSync('aws', ['s3api', 'get-object',
      '--bucket', bucket, '--key', objectKey, '--region', region,
      '--output', 'json', '--no-cli-pager', '--no-cli-auto-prompt', localFile],
      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }));
  } catch {
    throw new Error('S3 read failed. Keep this attempt and check the AWS read identity.');
  }
  let bytes = 0;
  const hash = createHash('md5');
  for await (const chunk of createReadStream(localFile)) {
    bytes += chunk.length;
    hash.update(chunk);
  }
  const md5 = hash.digest('hex');
  if (bytes !== file.file_size || md5 !== file.md5.toLowerCase()) {
    throw new Error('Byte count or MD5 mismatch. Keep the file; do not mark it ready.');
  }
  const ready = { runId: item.runId, jobId: run.data.remoteId,
    videoId: item.request.video_id, bucket, region, objectKey, storageVersionId: metadata.VersionId ?? null,
    bytes, md5, verifiedAt: new Date().toISOString(), localFile: resolve(localFile),
    deliverySha256: createHash('sha256').update(raw).digest('hex'), usage: delivery.usage };
  const readyFile = join(verification, 'ready.json');
  await writeFile(readyFile, JSON.stringify(ready, null, 2), { flag: 'wx', mode: 0o600 });
  console.log('Delivery verified:', readyFile);
} catch (error) {
  console.error(error instanceof Error ? error.message : 'Inspect the saved attempt.');
  process.exitCode = 1;
}
```


- [Boto3 GetObject](https://docs.aws.amazon.com/boto3/latest/reference/services/s3/client/get_object.html)
- [Commande AWS GetObject](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html)

<a id="verify-file"></a>

### Lancer la vérification

Après avoir enregistré le script, exécutez-le depuis le dossier de l’élément.

#### Python

##### Vérifier et lire le fichier de transmission

```bash
python verify-media.py
```


#### Node.js + AWS CLI

##### Vérifier et lire le fichier de transmission

```bash
set -euo pipefail
: "${DELIVERY_DIR:?Set the directory printed by recovery}"
node verify-media.mjs "$DELIVERY_DIR"
jq '{runId, jobId, bucket, region, objectKey, bytes, md5, storageVersionId}' \
  "$DELIVERY_DIR/verified/ready.json"
```



<a id="ready"></a>

### Transmettre ready.json à votre application

Le résultat attendu est Delivery verified et un enregistrement contenant les identifiants d’exécution et de tâche, le bucket, la région, la clé de l’objet, la taille vérifiée et le MD5. Le script crée cet enregistrement pour votre application. Archivez-le avec delivery.json et l’élément d’origine ; il reste disponible au-delà de la période de conservation du résultat API.

Pour la transcription, l’indexation ou un autre traitement, transmettez le localFile vérifié à votre processus de traitement. Pour proposer un téléchargement à l’utilisateur, passez à l’étape 6.

- [Conservation des résultats et stockage des médias](https://flashdata.dev/fr/docs/guides/save-results/reference.md#media)

<a id="serve"></a>

## 6. Donner un accès contrôlé depuis votre application

Dans votre backend, vérifiez l’autorisation de l’utilisateur et retrouvez son enregistrement ready dans votre propre stockage. Créez ensuite une URL S3 de téléchargement à durée limitée. Utilisez la destination enregistrée ; n’acceptez pas de bucket ni de clé d’objet fournis par le navigateur.


<a id="link-script"></a>

### Enregistrer le script de création du lien

Le SDK utilise l’identité AWS du backend autorisée en lecture. Aucune requête FlashData n’est envoyée.

L’URL désigne la version vérifiée de l’objet lorsque le versionnement S3 en fournit une. Sans identifiant de version, conservez chaque objet à sa clé sans le modifier après vérification. La lecture d’une version précise nécessite s3:GetObjectVersion ; une lecture sans version nécessite s3:GetObject.

#### Python

Créez create-download-link.py à côté de pipeline.py et copiez-y le code complet ci-dessous. Il utilise le paquet Boto3 installé au début.

##### create-download-link.py

```python
# create-download-link.py — run in your backend after authorizing the user.
import json
import os
import sys

import boto3
from botocore.config import Config
from pipeline import delivery_directory, read_json


def main():
    os.umask(0o077)
    # In an app, load this user's verified ready record from your own store.
    directory = delivery_directory() / 'verified'
    ready = read_json(directory / 'ready.json')
    if any(not isinstance(ready.get(key), str) or not ready[key]
           for key in ['bucket', 'region', 'objectKey', 'verifiedAt']):
        raise ValueError('Use the ready.json produced by the verification step.')
    destination = directory / 'access.json'
    if destination.exists():
        raise FileExistsError('Keep the existing access.json or choose a new output filename.')
    params = {'Bucket': ready['bucket'], 'Key': ready['objectKey']}
    version = ready.get('storageVersionId')
    if version and version != 'null':
        params['VersionId'] = version
    s3 = boto3.client('s3', region_name=ready['region'], config=Config(signature_version='s3v4'))
    url = s3.generate_presigned_url('get_object', Params=params, ExpiresIn=300, HttpMethod='GET')
    with destination.open('x', encoding='utf-8') as output:
        json.dump({'url': url, 'expiresInSeconds': 300}, output, indent=2)
    # Do not log the signed URL; return it only to the authorized user.
    print('Access record saved:', destination)


if __name__ == '__main__':
    sys.stdout.reconfigure(encoding='utf-8')
    sys.stderr.reconfigure(encoding='utf-8')
    try:
        main()
    except Exception as error:
        print(str(error), file=sys.stderr)
        sys.exit(1)
```


#### Node.js

Installez les paquets de signature dans le dossier de l’élément, puis enregistrez le code ci-dessous dans create-download-link.mjs, dans ce même dossier.

##### Installer le client de signature S3

```bash
test -f package.json || npm init -y
npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
```

##### create-download-link.mjs

```javascript
// create-download-link.mjs — run in your backend with its AWS read identity.
import { readFile } from 'node:fs/promises';
import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

try {
  const path = process.argv[2];
  if (!path) throw new Error('Pass the verified ready.json file.');
  const ready = JSON.parse(await readFile(path, 'utf8'));
  if (['bucket', 'region', 'objectKey', 'verifiedAt'].some(
    key => typeof ready[key] !== 'string' || !ready[key])) {
    throw new Error('Use the ready.json produced by the verification step.');
  }
  // Load this record from your own store after authorizing the requesting user.
  const version = ready.storageVersionId;
  const command = new GetObjectCommand({
    Bucket: ready.bucket, Key: ready.objectKey,
    ...(version && version !== 'null' ? { VersionId: version } : {}),
  });
  const client = new S3Client({ region: ready.region });
  const url = await getSignedUrl(client, command, { expiresIn: 300 });
  console.log(JSON.stringify({ url, expiresInSeconds: 300 }, null, 2));
} catch (error) {
  console.error(error instanceof Error ? error.message : 'Could not create a download link.');
  process.exitCode = 1;
}
```


- [Exemple d’URL présignée avec Boto3](https://docs.aws.amazon.com/boto3/latest/guide/s3-presigned-urls.html)
- [Exemple d’URL présignée avec AWS JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/javascript_s3_code_examples.html)
- [Accès S3 et expiration des URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)

<a id="download-link"></a>

### Renvoyer le lien à l’utilisateur autorisé

Le résultat attendu est un fichier privé access.json contenant url et expiresInSeconds: 300. Votre backend renvoie uniquement l’URL à l’utilisateur autorisé. Toute personne qui la détient peut télécharger le fichier pendant cinq minutes au maximum ; elle peut expirer plus tôt avec les identifiants de signature.

Créez un nouveau lien à partir de l’enregistrement ready sauvegardé lors de la prochaine demande d’accès. Conservez la clé et la version de l’objet dans votre base de données, plutôt que l’URL temporaire comme adresse du média. Cet exemple local s’arrête si access.json existe déjà.

#### Python

##### Créer un lien valable cinq minutes

```bash
python create-download-link.py
```


#### Node.js

##### Créer un lien valable cinq minutes

```bash
(
set -euo pipefail
umask 077
: "${DELIVERY_DIR:?Set the directory printed by recovery}"
# Keep the signed link in a private file; do not log it or paste it into chat.
set -C
node create-download-link.mjs "$DELIVERY_DIR/verified/ready.json" \
  > "$DELIVERY_DIR/verified/access.json"
)
```



<a id="restart"></a>

## Reprendre à la dernière étape confirmée

| Situation | Action suivante |
| --- | --- |
| Tâche acceptée / délai d’attente local dépassé | Relancez runs recover avec le même runId dans un nouveau répertoire de tentative. |
| Accès S3 refusé ou lecture interrompue | Corrigez l’identité AWS de lecture ou la connexion. Reprenez dans un nouveau répertoire et vérifiez à nouveau ; conservez le fichier partiel précédent. |
| Taille, MD5 ou destination non conformes | Arrêtez le traitement. Comparez le manifeste, la version de l’objet et la destination prévue avant d’utiliser le média. |
| verified/ existe déjà | Lisez son ready.json ou examinez sa vérification incomplète. Le script ne l’écrasera pas. |
| Le lien de téléchargement de l’application a expiré | Vérifiez à nouveau l’autorisation et signez l’objet ou la version enregistrés. Ne soumettez pas un autre téléchargement FlashData. |
| run_id_input_conflict | La requête a changé. Reprenez l’exécution d’origine ; utilisez un nouveau runId uniquement pour une nouvelle sortie voulue. |
| 401 / 403 / 402 / 429 | Corrigez l’accès, les permissions ou le solde ; respectez Retry-After. Examinez les opérations enregistrées avant de retenter une soumission. |


<a id="scale"></a>

## Appliquer les mêmes étapes à une file d’attente

1. Commencez par un seul élément en cours de traitement. Consultez les limites actuelles avant d’augmenter le nombre de traitements simultanés dans votre application.
2. Conservez un runId durable pour chaque version de vidéo ou de sortie, avec un préfixe de destination distinct. Enregistrez le compte, l’identifiant de tâche et le résultat final dans la base de données de votre application.
3. Conservez le répertoire d’état CLI entre les redémarrages des processus. Des machines distinctes nécessitent une coordination partagée dans l’application ; un journal local ne déduplique pas les opérations de répertoires d’état indépendants.
4. Utilisez ready.json pour transmettre le résultat aux traitements suivants. Conservez les éléments en échec séparément afin de réutiliser les livraisons réussies.

- [Limites du compte](https://flashdata.dev/fr/docs/guides/usage-and-limits/reference.md)
- [Identifiants sur serveur et dans les conteneurs](https://flashdata.dev/fr/docs/guides/production-deployment/reference.md)
- [Planification des tâches récurrentes](https://flashdata.dev/fr/docs/guides/recurring-tasks/reference.md)
