Support des CGI

version 2004 (Modifiée)

Le serveur Web 4D permet de tirer parti des CGI (Common Gateway Interface). Les CGI sont aux pages Web ce que les plug-ins sont aux méthodes 4D. Appelé par le serveur Web, le CGI exécute une tâche et retourne une réponse — une page Web complète ou du code HTML venant s'insérer dans une page envoyée par le serveur. Des CGI sont fréquemment utilisés pour afficher les compteurs d'accès, gérer les livres d'or (guestbook), recevoir le résultat d'un formulaire (form to mail), etc. Une multitude de CGI sont aujourd'hui disponibles. La plupart d'entre eux sont dans le domaine public.

Note : Le terme CGI désigne, à l'origine, la norme définissant l'interfaçage des applications externes avec les serveurs HTTP. Par extension, "CGI" est aujourd'hui utilisé pour désigner ces applications externes elles-mêmes.

4D peut utiliser des CGI de deux manières :

• le serveur Web 4D peut exécuter des CGI en mode automatique ou en mode manuel

• le serveur Web 4D peut être interrogé par tout serveur HTTP via des extensions de type CGI et ISAPI (Windows uniquement).

4D prend en charge tous les types de CGI, sous Mac OS X et sous Windows. Un CGI se présente sous la forme d'un programme exécutable, d'un script PERL ou d'une DLL s'interfaçant avec un serveur Web.

- des exécutables (.EXE) utilisant la "console" et les variables d'environnement. Le code source est généralement multi-plate-forme (Windows et Unix). Leurs noms sont de la forme nnnn.exe ou nph-nnnn.exe. Pour plus d'informations sur ce type de CGI, veuillez consulter le site http://hoohoo.ncsa.uiuc.edu/cgi/.

- des scripts PERL utilisant la "console" et les variables d'environnement. Ces CGI nécessitent la présence d'un interpréteur permettant de les exécuter. Ils présentent l'avantage d'être entièrement multi-plate-forme (Windows, Unix et Mac OS). Leurs noms sont de la forme nnnn.pl, nph-nnnn.pl, nnnn.cgi ou encore nph-nnnn.cgi.

Pour plus d'informations sur ce type de CGI, veuillez consulter le site http://www.perl.com/.

- des DLL ISAPI, c'est-à-dire des extensions pour IIS (Internet Information Server). Leurs noms sont de la forme nnnn.dll ou nph-nnnn.dll. Pour des raisons de performances, les DLL appelées de la sorte ne sont déchargées qu'à l'arrêt du serveur Web. Pour plus d'informations sur ce type de CGI, veuillez consulter le site http://www.microsoft.com/iis/.

L'appel automatique d'un CGI s'effectue par l'intermédiaire d'un URL, d'une action de formulaire ou d'une balise HTML inséré(e) dans une page, en fonction de la tâche effectuée par le CGI. Dans tous les cas, la chaîne HTML doit contenir /cgi-bin/ suivi du nom du CGI et éventuellement d'un chemin d'accès (utilisant la syntaxe HTML) ainsi que d'une chaîne d'interrogation.

Par exemple, l'URL "http://195.1.2.3/cgi-bin/search.exe" provoquera l'exécution du CGI search.exe. De même, si vous placez la balise <IMG SRC="/special/cgi-bin/counter.exe"> au sein d'une page HTML, le CGI counter.exe sera exécuté lors de l'envoi de la page.

Pour pouvoir être appelés, les CGI doivent obligatoirement être placés à la racine d'un dossier nommé cgi-bin. Ce dossier doit lui-même être situé à la racine du serveur Web ou dans un sous-dossier. Il peut y avoir plusieurs dossiers cgi-bin par serveur. Ce dossier peut contenir d'autres fichiers que des exécutables, mais seuls ces derniers peuvent être appelés depuis un client Web.

Voici des exemples d'emplacements et les URL pouvant être appelés :

L'appel de CGIs en mode manuel requiert l'utilisation de la commande FIXER EXECUTABLE CGI. Cette commande permet notamment d'exécuter un CGI sans que celui-ci soit visible pour l'utilisateur Web dans l'URL.

Pour plus d'informations sur ce point, reportez-vous à la description de cette commande.

L'appel d'un CGI ne modifie jamais l'environnement de 4D (sélections, variables...).

4D n'impose aucune limite de taille de la réponse. Cependant, la durée maximum de traitement allouée au CGI est fixée à 30 secondes. Au-delà de ce délai, le serveur Web retournera une erreur.

Un CGI est toujours exécuté hors contexte, quel que soit le mode depuis lequel il a été appelé.

A noter toutefois qu'en mode contextuel, il est conseillé de ne pas utiliser de CGI qui renvoie du code HTML, car il y a dans ce cas risque de désynchronisation du contexte.

Lorsque l'appel d'un CGI génère une erreur, 4D retourne une des réponses suivantes, sous forme de page HTML standard :

• Non trouvé : le CGI n'a pu être localisé par 4D, ou bien l'interpréteur PERL n'est pas installé

• Interdit : le client Web demande autre chose qu'un exécutable dans un dossier [cgi-bin]

• Timeout : le CGI n'a pu traiter la requête en 30 secondes

• Mauvaise réponse : la réponse du CGI n'a pu être traitée par 4D ou la DLL ISAPI a causé une exception

• Erreur interne : mémoire saturée, etc.

Note : Lorsqu'un CGI ne fonctionne pas, vérifiez que les privilèges d'exécution du CGI sont suffisants et que les retours à la ligne dans le script CGI sont corrects.

Ce paragraphe est principalement destiné aux programmeurs souhaitant développer des CGI pour leur bases 4D.

• Variables d'environnement

4D définit les variables d'environnement en conformité avec les spécifications CGI/1.1, avec les précisions suivantes :

GATEWAY_INTERFACE : toujours "CGI/1.1"

SERVER_SOFTWARE : toujours de la forme "4D WebStar_D/version"

SERVER_PROTOCOL : toujours "HTTP/1.0"

SERVER_PORT_SECURE : contient "1" si la connexion HTTP est sécurisée, sinon "0".

PATH_TRANSLATED : contient le chemin d'accès complet de la racine HTML du serveur, auquel est ajouté la portion de chemin qui suit le nom du CGI. Par sécurité, la portion de chemin ne peut contenir les séquences // ou ..

Exemple : Racine du serveur C:/web

Pour un appel CGI du type /cgi-bin/cgi.exe/path, PATH_TRANSLATED vaut "C:/web/path". Pour un appel CGI du type /cgi-bin/cgi.exe/../path, 4D renvoie l'erreur Interdit.

REMOTE_IDENT : nom d'utilisateur, sinon non définie

HTTP_AUTHORIZATION, HTTP_CONTENT_LENGTH et HTTP_CONTENT_TYPE : non définies

ALL_HTTP et URL sont définies dans le cas d'appels de DLL ISAPI.

CERT_xxx et HTTPS_xxx sont définies si la connexion est sécurisée (pour les DLL uniquement).

Note : La commande FIXER VARIABLE ENVIRONNEMENT permet de définir ces variables.

En plus des variables d'environnement standard, 4D ajoute des variables texte du type FORMVAR_nomvariable :

- si la requête est envoyée avec la méthode "POST", ces variables correspondent aux zones de saisie du formulaire (par exemple FORMVAR_NOM, FORMVAR_PRENOM...) à l'exception des champs binaires (INPUT TYPE="FILE"). Ce système peut être utilisé avec les formulaires encodés "www/url-encoded" et "multipart/form-data".

- si la requête est envoyée avec la méthode "GET", ces variables correspondent aux valeurs passées par la chaîne d'interrogation (par exemple, dans le cas de l'URL .../cgi.exe?nom=martin&code=75, FORMVAR_NOM vaudra "martin" et FORMVAR_CODE vaudra "75").

Ce fonctionnement présente l'avantage de faciliter le traitement des formulaires (il n'est pas nécessaire d'analyser les chaînes a=1&b=2&...), mais rend le CGI spécifique à 4D.

• Traitement des réponses retournées par les CGI

Si le nom du CGI (exécutable Windows ou script PERL) débute par nph- (No Parsing Header), 4D retourne la réponse "telle quelle" au client Web. Dans ce cas, il revient au CGI de respecter la norme HTTP. En ce qui concerne les DLL ISAPI, 4D n'analyse jamais la réponse, que le préfixe nph- soit présent ou non.

Si ce n'est pas le cas, 4D se charge de renvoyer l'en-tête HTTP :

- si "Content-Type" n'est pas spécifié par le CGI, 4D renvoie systématiquement "Content-Type: text/html",

- si "Location" est spécifié, 4D ignore les autres éléments de la réponse et effectue une redirection HTTP,

- si "Status" n'est pas spécifié, 4D renvoie "HTTP/1.0 200 OK".

4D accepte tout type de changement de ligne (Windows-CRLF, Mac OS-CR, Unix-LF) dans l'en-tête de la réponse HTTP et se charge de la reformater.

Dans le cas des DLL ISAPI, 4D accepte les traitements asynchrones (HttpExtensionProc retourne HSE_STATUS_PENDING). L'appel à ServerSupportFunction (HSE_REQ_DONE_WITH_SESSION) doit avoir lieu dans les 30 secondes. Si la fonction TerminateExtension est définie, elle est toujours appelée avec la valeur HSE_TERM_MUST_UNLOAD.

4e Dimension est accompagné de deux extensions, 4DISAPI.DLL et NPH-CGI4D.EXE. Le but de ces extensions est de permettre à un serveur HTTP de transmettre des requêtes au serveur Web 4D. Avec ces extensions, 4D peut être interrogé par tout autre serveur HTTP. Ce mécanisme autorise par exemple le développement de systèmes dans lesquels un serveur Web 4D non sécurisé peut être interrogé via un autre serveur HTTP, tournant lui en mode sécurisé.

Note : Ces deux extensions sont disponibles sous Windows uniquement.

• L'extension 4DISAPI.DLL respecte les spécifications définies par ISAPI (Internet Services Application Programming Interface). La technologie ISAPI a été développée à l'origine par Microsoft® pour le serveur IIS, mais a été depuis rendue compatible avec de nombreux serveurs HTTP tels que Netscape®, Apache® ou Sambar®.

• L'extension NPH-CGI4D.EXE respecte les spécifications des CGI (Common Gateway Interface) et peut être utilisée avec l'ensemble des serveurs compatibles CGI.

Le fonctionnement de ces deux extensions est identique. La compatibilité CGI est plus largement répandue parmi les serveurs HTTP, toutefois les performances des extensions CGI sont généralement inférieures à celles des extensions ISAPI.

Le principe de fonctionnement de ces extensions est le suivant : un serveur HTTP "A" publie des pages sur Internet, et un autre serveur HTTP, "B", est par exemple un 4D Server utilisé en Intranet. Afin que les deux serveurs puissent communiquer, il vous suffit d'ajouter une extension 4DISAPI ou NPH-4DCGI dans le répertoire [Scripts] du serveur A.

Lorsqu'un navigateur Web envoie une requête au serveur A, celui-ci la retransmet au serveur B via l'extension 4D ISAPI ou NPH-4DCGI, par l'intermédiaire de l'URL. La réponse est ensuite acheminée au navigateur en sens inverse. Le corps de la requête ou de la réponse HTTP n'est jamais modifié par les extensions.

La requête initiale envoyée au serveur A peut être effectuée en clair ou en mode sécurisé (SSL). La communication entre les deux serveurs HTTP et l'extension 4DISAPI.DLL s'effectue en clair.

Note : Les extensions 4DISAPI et NPH-4DCGI ne sont pas compatibles avec le mode contextuel du serveur Web 4D.

Le schéma suivant illustre ce principe :

• Les extensions reconnaissent les méthodes GET, HEAD et POST, elles gèrent les différents statuts renvoyés par 4D (200 OK, 302 Moved Temporarely, 404 Not Found...).

• Il n'est pas possible de procéder à une authentification au niveau HTTP via l'extension 4DISAPI ou NPH-CGI4D. Pour cela, il est nécessaire d'utiliser un formulaire HTML (ce qui est parfaitement envisageable en connexion sécurisée).

Note : Les extensions sont avant tout destinées à être utilisées pour recevoir et renvoyer des données dynamiques, et en particulier pour poster des données. Le simple service de pages Web n'offre pas des performances optimales en cas de transit via des extensions ISAPI ou CGI.

L'installation des extensions 4DISAPI et NPH-CGI4D s'effectue par simple copie des fichiers 4DISAPI.DLL ou NPH-CGI4D.EXE dans le dossier [Scripts] du serveur HTTP.

Chaque extension installée doit être accompagnée d'un fichier de configuration (de type *.INI). Le fichier .INI doit porter le même nom que l'extension (par exemple 4DISAPI.INI). L'extension et son fichier de configuration doivent être placés dans le même dossier.

Vous pouvez configurer un serveur HTTP de manière à ce qu'il puisse cibler plusieurs autres serveurs HTTP. Dans ce cas, placez dans le dossier [Scripts] du serveur HTTP autant d'extensions que de serveurs-cibles. Il vous suffit de les renommer (par exemple 4DISAPI2.DLL, 4DISAPI3.DLL, etc.). Veillez à insérer un fichier de configuration par extension, et à le renommer en conséquence (4DISAPI2.INI, 4DISAPI3.INI, etc.).

Le fichier .INI est constitué d'une seule section : [Forward]. Cette section accepte les commandes suivantes :

• TargetServer =

Nom ou adresse IP du serveur Web à cibler (par exemple monserveur.net ou 192.193.194.195). Laisser la chaîne vide pour repérer le serveur par son adresse si la résolution par nom n'est pas disponible

Le nom "localhost" est reconnu comme étant l'adresse 127.0.0.1.

Par défaut, l'adresse 127.0.0.1 est utilisée.

• TargetPort =

Port sur lequel le serveur-cible écoute (par exemple 81). Par défaut, le port 8080 est utilisé.

• Timeout =

Délai maximum d'attente de la réponse du serveur (exprimé en secondes). La valeur par défaut est de 30 secondes.

• Allowed =

Liste des URL autorisés, séparés par des virgules. Par exemple : /pages, /img pour n'autoriser que les URL commençant par /pages et /img. Pour autoriser la totalité du site, inscrivez une barre oblique seule / (paramétrage par défaut).

• Forbidden =

Liste des URL interdits, séparés par des virgules. Par exemple : /4dmethod, /pages2 pour interdire les URL commençant par /4dmethod et /pages2. Pour ne rien interdire, ne saisissez rien dans la liste (paramétrage par défaut).

Compte tenu des exemples d'autorisations et d'exclusions fournis ci-dessus, les URL suivants du serveur-cible seront accessibles ou non :

Si un URL déclaré interdit est sollicité, l'extension retourne directement l'erreur "HTTP/1.0 403 Forbidden".

Les extensions 4DISAPI et NPH-CGI4D acceptent les URLs suivants :

• Appel de 4D (4D ne reçoit que la portion de chemin qui suit le nom de l'extension) :

http://adresse-serveur/cgi-bin/4disapi.dll/[chemin d'accès]

http://adresse-serveur/cgi-bin/nph-cgi4d.exe/[chemin d'accès]

• Test de fonctionnement de l'extension (écho de la requête) :

http://adresse-serveur/cgi-bin/4disapi.dll/~~echo

http://adresse-serveur/cgi-bin/nph-cgi4d.exe/~~echo

• Informations sur l'extension (support technique) :

http://adresse-serveur/cgi-bin/4disapi.dll/~~info

http://adresse-serveur/cgi-bin/nph-cgi4d.exe/~~info

Les informations suivantes sont retournées :

- nom et version de l'extension, par exemple "Script name: 4disapi.dll (6.7.0b1.2)"

- nom et version du serveur appelant l'extension, par exemple "Server software: 4D_WebStar_D/6.7"

- version du protocole HTTP, par exemple "Server protocol: HTTP/1.0"

- version du protocole CGI, par exemple "Gateway interface: CGI/1.1"

• Test du serveur cible (est-il joignable ?) :

http://adresse-serveur/cgi-bin/4disapi.dll/~~target

http://adresse-serveur/cgi-bin/nph-cgi4d.exe/~~target

La réponse est soit :

"Good: target server reached." : le serveur cible a répondu (quel que soit le contenu de la réponse).

soit "Bad: target server not reached." : le serveur est injoignable ou n'a pas répondu.

Dans ce cas, la raison de l'échec peut être :

- pas de fichier de configuration ;

- l'adresse ou le port cible est incorrect ;

- le serveur cible n'est pas en service ;

- le serveur a traité la requête mais est incapable de répondre.

Note sur 4D WebSTAR : 4D WebSTAR® est un des serveurs Web les plus répandus sur la plate-forme Mac OS. Diverses possibilités d'interactions directes sont possibles entre 4D WebSTAR et 4e Dimension à l'aide du plug-in 4D WebSTAR 4D Link. Pour plus d'informations sur ce plug-in, veuillez consulter la documentation de 4D WebSTAR.

FIXER EXECUTABLE CGI, FIXER VARIABLE ENVIRONNEMENT.