La Compagnie Cybernétique de Sirius est heureuse de vous présenter son nouveau protocole de consultation de fichier HyperProtoGalactifornet de Transfération Siriusienne Ultra-Réglementée¹ (HPGTSUR).
Ce protocole, reposant sur TCP, est orienté client/serveur. Le serveur expose un système de fichiers, composé de répertoires et de… fichiers. Un client a alors la capacité de se déplacer dans l’arborescence, de lister les fichiers présents dans le répertoire courant, et de télécharger les fichiers présents.
Notez que les noms des fichiers sont en UTF-8, et peuvent comporter
la plupart des caractères, à l’exception notable de l’espace d’une part,
et du caractère / qui est utilisé comme séparateur.
La Compagnie Cybernétique de Sirius espère que vous aurez toute satisfaction dans l’utilisation de ce protocole.
Un paquet est structuré de la manière suivante :
| Champ | Taille | Description |
|---|---|---|
| ID requête | 4 octets | Identifiant de la requête |
| Requête / réponse | 1 bit | 1 pour requête, 0 pour réponse |
| Erreur | 1 bit | Pour réponse uniquement, 1 si erreur, 0 sinon |
| Type commande | 6 bits | Type de commande (cf ci-après) |
| Séquence | 14 bits | Numéro de séquence (0-16383) |
| Taille payload | 10 bits | Taille de la payload (0-1023) |
| Payload | Variable | Contenu (dépend du type de commande) |
| CRC | 4 octets | Somme de contrôle |
Les champs sont orientés gros-boutiste.
L’ID de requête est un entier sur 4 octets, commun à l’ensemble des échanges liés à une commande : le paquet de requête, le ou les paquets de réponse et/ou le paquet d’erreur associé. La génération de l’identifiant est à la charge du client, mais il doit être unique à l’ensemble d’une transmission globale entre un client et un serveur; dans le cas contraire les conséquences ne sont pas spécifiées.
Bit indiquant si le paquet est une requête (émise par un client, valeur 1) ou une réponse (émise par un serveur, valeur 0).
Bit positionné dans un paquet émis par le serveur si une erreur a été détectée dans une requête. Dans ce cas, la payload contient un message d’erreur l’explicitant.
Par exemple: Fichier truc.txt non trouvé.
Les commandes disponibles pour les requêtes sont les suivantes :
LST (01) : lister les fichiers présents dans le
répertoire courant.CHFLD (02) : changer le répertoire courant.PWD (03) : retourne le répertoire courant.DWNLD (04) : télécharger un fichier.RSND (05) : réémettre un paquet.Dans le cas d’une réponse, le champ contient la commande à laquelle la réponse est associée.
Le protocole supporte la fragmentation des réponses. Si la payload est plus grande que 1023 octets, il la découpe en plusieurs paquets, en incrémentant le numéro de séquence. Attention, il peut arriver que les fragments n’arrivent pas dans le bon ordre ! C’est même assez fréquent.
Si la valeur du champ séquence est 0, cela signifie que la réponse n’est pas fragmentée. Elle l’est lorsque le numéro de séquence est strictement positif. Notez que, par conséquent, les numéros de fragments commencent à l’index 1.
Contenu du paquet. Pour les requêtes émises par un client, il peut
s’agir de paramètres (par exemple le nom du répertoire pour une commande
CHFLD). Pour les réponses, le contenu dépend de la commande
de la requête correspondante. Cf. ci-après la description de chacune des
commandes. Une réponse contenant une payload de plus de 1023 octets sera
découpée en plusieurs paquets (Cf. Séquence ci-dessus).
Une somme de contrôle permettant de s’assurer de l’intégrité du
paquet. Elle est calculée sur l’intégralité du contenu du paquet, hormis
le CRC lui-même évidemment. L’algorithme utilisé est le
classique CRC32. Dans le cas où l’on reçoit un paquet dont le CRC
n’est pas valide, on peut demander la réémission du paquet à l’aide de
la commande RSND.
Dans les exemples ci-dessous, les données binaires sont exprimées sous forme hexadécimale, et les payloads sous forme textuelle.
Attention, les payloads des erreurs documentées ci-dessus sont données à titre indicatif mais peuvent varier suivant l’ implémentation du serveur.
LST/01)Cette commande demande à lister le contenu du répertoire courant. La payload de cette commande doit être vide, sinon le serveur retourne une erreur.
Dans la réponse, le serveur indique la liste des répertoires et des fichiers contenus dans le répertoire courant. Chaque élément est préfixé par un D pour un répertoire ou un F pour un fichier. Les différents éléments sont séparés par des retours chariot ().
Exemple de commande :
<ID>|0|0|01|00|0||<CRC>Exemple de réponse :
<ID>|1|0|01|00|39|F foo.txt\nD Folder1\nD Folder2\nF bar.txt|<CRC>Exemples d’erreur :
<ID>|1|1|01|00|40|Le contenu de la requête doit être vide.|<CRC>
<ID>|1|1|01|00|34|La somme de contrôle est invalide.|<CRC>CHFLD/02)Cette commande permet de changer le répertoire courant. Il prend en
paramètre (dans la payload) le nom du répertoire dans lequel se
positionner relativement au répertoire courant. Il n’est pas possible de
se déplacer de plusieurs répertoires en une seule commande. Pour
«remonter» dans l’arborescence, on demande à se déplacer dans le pseudo
répertoire ...
En cas de succès, la payload de la réponse est vide.
Exemple de commande :
<ID>|0|0|02|00|7|Folder1|<CRC>Exemple de réponse :
<ID>|1|0|02|00|0||<CRC>Exemples d’erreur :
<ID>|1|1|02|00|27|Le répertoire n'existe pas.|<CRC>
<ID>|1|1|02|00|34|La somme de contrôle est invalide.|<CRC>PWD/03)Cette commande retourne le répertoire courant. Aucun paramètre n’est attendu dans la requête (dans le cas contraire, le serveur répondra par une erreur).
En cas de succès, la payload de la réponse contient le chemin absolu
du répertoire courant. Il s’agit de la concaténation des différents
sous-répertoire avec le séparateur /.
Exemple de commande :
<ID>|0|0|03|00|0||<CRC>Exemple de réponse :
<ID>|1|0|03|00|12|root/Folder1|<CRC>Exemples d’erreur :
<ID>|1|1|03|00|40|Le contenu de la requête doit être vide.|<CRC>
<ID>|1|1|04|00|37|La somme de contrôle est invalide.|<CRC>DWNLD/04)Cette commande retourne le contenu d’un fichier. Le nom du fichier à télécharger est passé dans la payload. Seul un fichier du répertoire courant peut-être téléchargé.
En cas de succès, la payload de la réponse contient le contenu binaire du fichier. Celle-ci sera fragmentée si le fichier fait plus de 500 octets.
Exemple de commande :
<ID>|0|0|04|00|7|foo.txt|<CRC>Exemple de réponse :
<ID>|1|0|04|01|1023|Ceci est le contenu du fichier de test foo.txt [...]|<CRC>
<ID>|1|0|04|02|1023|Le fichier fait plus de 500 octets ce qui implique une réponse fragmentée [...]|<CRC>
<ID>|1|0|04|03|43|Fin du fichier. (c'est toujours du contenu)|<CRC>Exemples d’erreur :
<ID>|1|1|03|00|32|Le fichier demandé n'existe pas.|<CRC>
<ID>|1|1|04|00|34|La somme de contrôle est invalide.|<CRC>RSND/05)Dans le cas où le client reçoit une réponse invalide (la somme de contrôle ne correspond pas au contenu), il peut redemander l’émission du paquet par le serveur. Pour cela, la requête doit contenir l’identifiant et le numéro de séquence exacts de la réponse à répéter. De plus, la payload de cette commande doit être vide, le serveur retournant une erreur dans le cas contraire.
Attention, la plupart des implémentations des serveurs ne sont pas capables de répondre à une demande concernant une ancienne commande. Si vous demandez la réémission d’un paquet d’une commande alors qu’une autre a été envoyée entre temps, il est probable que le serveur retourne une erreur.
Par exemple, si le client a reçu la réponse suivante :
<ID>|1|0|04|<SEQ>|<taille>|<contenu d'un fichier binaire>|<bad CRC>il peut demander la réémission du paquet avec la commande
RSND en reprenant l’identifiant de requête et le numéro de
séquence de la réponse invalide :
<ID>|0|0|05|<SEQ>|0||<CRC>Exemple de réponse :
<ID>|1|0|04|<SEQ>|<taille>|<contenu d'un fichier binaire|<CRC>Exemples d’erreur :
<ID>|1|1|05|00|22|Le paquet est inconnu.|<CRC>
<ID>|1|1|05|00|27|La payload doit être vide.|<CRC>
<ID>|1|1|05|00|34|La somme de contrôle est invalide.|<CRC>
<ID>|1|1|05|00|34|Ce paquet n'a pas été retrouvé.|<CRC>¹: La Compagnie tient à présenter ses excuses pour les dommages occasionnés à la lecture de ce nom, choisi parmi 1823 alternatives par les 6 sous-groupes de la commission de l’administration Vogon, premier acquéreur du système.
© Compagnie Cybernétique de Sirius, tous droits réservés, et merci pour le poisson.