Gateway Workers

Lisez le guide Forward actuel avant d'implémenter un Worker. Il définit comment Gateway invoque les Workers sur le trafic HTTP autorisé. Récupérez la page pertinente ci-dessous plutôt que de copier la configuration, les payloads API ou les limites dans le projet de mémoire.

Workflow

1. Inspectez le Worker existant et choisissez un modèle de Worker pour la transformation, la réponse synthétique ou la tâche de fond requise.
2. Exportez une classe GatewayMiddleware nommée étendant WorkerEntrypoint depuis cloudflare:workers. Implémentez handle(request, context, next) et retournez une Response. Gateway appelle cette méthode via RPC. Un gestionnaire fetch() par défaut seul n'implémente pas le contrat Forward.
3. Pour TypeScript, suivez les instructions actuelles d'installation de package et d'import de types du modèle choisi.
4. Utilisez le deuxième argument pour le contexte Gateway. Il décrit la requête originale et reste inchangé quand le Worker modifie la requête. Gardez-le distinct de this.ctx (contexte d'exécution Workers) et this.env (bindings).
5. Continuez la requête de l'utilisateur avec next(request) au maximum une fois, ou retournez une réponse synthétique sans l'appeler. next() cible toujours la destination originale. Les modifications de l'URL ou de l'hôte de destination sont ignorées, et il ne peut pas rediriger, réessayer ou se diviser. Utilisez fetch() pour envoyer une requête vers une autre destination. Elle crée une sous-requête indépendante qui n'hérite pas des stratégies Gateway ou de la configuration de sortie de l'utilisateur.

Contexte

Utilisez les types publiés et la référence de contexte pour les noms et la disponibilité des champs. Traitez une identité falsy (!identity) comme anonyme et protégez les valeurs de posture optionnelles. Appelez await context.identity() ou await context.devicePosture() uniquement si nécessaire. Les deux getters peuvent rejeter. Capturez les échecs de recherche séparément des valeurs manquantes et décidez comment gérer chacun quand le Worker en dépend. Utilisez l'identité fournie par Gateway plutôt que les en-têtes d'identité fournis par le client.

Comportement de Gateway

• Seule la première stratégie Forward correspondante invoque un Worker. L'invocation du Worker ne confirme pas l'inspection réussie du corps. Suivez l'ordre d'inspection du guide Forward.
• Gateway inspecte la réponse finale, y compris les réponses synthétiques. Les octets de requête modifiés ne sont pas inspectés à nouveau avant d'atteindre l'origine.
• Consultez les limitations du guide Forward avant de choisir le trafic : HTTPS nécessite le déchiffrement, WebSockets contournent le Worker, et le trafic VPC correspond est supprimé. Les échecs d'invocation du Worker échouent en fermé.

Validation

Vérifiez les types par rapport aux types Gateway installés et testez l'entrypoint RPC nommé, y compris zéro ou un appel de continuation et les valeurs de contexte que le Worker utilise. Puis testez une requête autorisée via une stratégie Gateway Forward limitée. Une requête directe à un gestionnaire fetch() par défaut ne valide pas le chemin Gateway. Suivez la procédure de test du modèle choisi et les étapes de dépannage du guide Forward.

Vérifiez les règles de réponse et de streaming : retournez un statut final de 200 à 599, ne retournez aucun corps pour les requêtes HEAD ou les statuts 204, 205 et 304, et streamez les corps plutôt que de les bufferiser.

Compétences associées

• cloudflare-one : conception des stratégies Gateway, chemins de trafic, identité, TLS et lancement.
• workers-best-practices : streaming, bindings, types d'environnement générés, travail de fond, observabilité et tests runtime.
• Sélection CLI : choisissez la compétence cf-cli ou wrangler existante pour la configuration du projet et le déploiement.