quickserv
v0.3.0
Service Web rapide et sans settup
QuickServ facilite la création d'applications Web, peu importe le langage de programmation que vous utilisez.
QuickServ est un serveur Web unique sans dépendance, lié à un seul file qui:
read et write QuickServ apporte le plaisir grisant de l'Internet des années 1990 dans les années 2020. Il est inspiré par l'interface de passerelle commune (CGI), mais est beaucoup plus facile à configurer et à utiliser. Contrairement à CGI, cela fonctionne hors de la boîte sans rechercher des fichiers journaux obscurs, sans apprendre comment fonctionnent les en-têtes HTTP, sans jouer avec des bits d'autorisation, sans se soucier des COR, ne se demandant pas où mettre vos scripts et sans lutte avec les configurations Apache mod_cgi .
Contrairement à CGI, vous n'avez pas à savoir ce que quelque chose du paragraphe précédent signifie utiliser QuickServ.
Il est parfait pour:
QuickServ ne doit pas être utilisé sur Internet public. Il ne doit être utilisé que sur des réseaux privés.
L'utilisation de QuickServ est aussi simple que de télécharger le programme, de le faire glisser vers votre dossier de projet et de double-cliquer pour s'exécuter. Il détecte automatiquement les fichiers à exécuter et lesquels servir directement à l'utilisateur.
Télécharger pour Windows.
Faites un dossier de projet et ajoutez-y des fichiers. Par exemple, si Python est installé, créez un fichier appelé test.py dans le dossier du projet contenant:
#!python
# Put your code here. For example:
import random
print ( random . randint ( 0 , 420 ))
Étant donné que test.py commence par #!something , où something test.py est la commande pour exécuter le fichier, QuickServ saura l'exécuter. Si QuickServ n'exécute pas votre fichier, assurez-vous d'ajouter cela au début.
Sur Windows, QuickServ sait également exécuter automatiquement des fichiers qui se terminent par .exe et .bat . Tout autre type de fichier doit commencer par #!something s'il doit être exécuté.
Déplacez le fichier quickserv_windows_x64.exe téléchargé dans le dossier du projet.
Double-cliquez sur quickserv_windows_x64.exe Dans le dossier du projet pour démarrer QuickServ. Autorisez l'accès via Windows Defender s'il est invité.
Accédez à http://127.0.0.1:42069 (ou à l'adresse indiquée par QuickServ) pour vous connecter à votre application Web. Dans l'exemple, pour exécuter test.py , accédez à http://127.0.0.1:42069/test.py.
Téléchargez la bonne version pour votre ordinateur. Si nécessaire, vérifiez le type de processeur de votre Mac. Vous devrez décompresser les fichiers après les télécharger.
Faites un dossier de projet et ajoutez-y des fichiers. Par exemple, si Python est installé, créez un fichier appelé test.py dans le dossier du projet contenant:
#!python
# Put your code here. For example:
import random
print ( random . randint ( 0 , 420 ))
Si vous créez le fichier avec TextEdit, vous devrez entrer au Format > Make Plain Text pour enregistrer le fichier dans le format correct.
Étant donné que test.py commence par #!something , où something test.py est la commande pour exécuter le fichier, QuickServ saura l'exécuter. Si QuickServ n'exécute pas votre fichier, assurez-vous d'ajouter cela au début.
Sur Mac, QuickServ sait également exécuter automatiquement des fichiers qui ont été compilés. Tout autre type de fichier doit commencer par #!something s'il doit être exécuté.
Déplacez le fichier quickserv_macos_x64 ou quickserv_macos_arm64 téléchargé dans le dossier du projet.
Cliquez avec le bouton droit sur quickserv_macos_x64 ou quickserv_macos_arm64 dans le dossier du projet et sélectionnez "Ouvrir". Ensuite, appuyez sur "Open" dans la boîte de dialogue de confirmation. Après l'avoir exécuté une fois de cette façon, vous pourrez démarrer QuickServ en double-cliquez simplement sur le fichier.
Accédez à http://127.0.0.1:42069 (ou à l'adresse indiquée par QuickServ) pour vous connecter à votre application Web. Dans l'exemple, pour exécuter test.py , accédez à http://127.0.0.1:42069/test.py.
Il est plus facile d'installer et d'exécuter via la ligne de commande. Ouvrez le terminal.
Entrez les commandes suivantes. Un mot de passe peut être requis pour les premières commandes.
# Download
sudo curl
--location
--output /usr/local/bin/quickserv
https://github.com/jstrieb/quickserv/releases/latest/download/quickserv_raspi_arm
# Make executable
sudo chmod +x /usr/local/bin/quickserv
# Make a project folder
mkdir -p my/project/folder
# Go to project folder
cd my/project/folder
# Add a test file
cat << EOF > test.py
#!python3
# Put your code here. For example:
import random
print(random.randint(0, 420))
EOF
# Run QuickServ
quickserv Accédez à http://127.0.0.1:42069 (ou à l'adresse indiquée par QuickServ) pour vous connecter à votre application Web. Par exemple, pour exécuter test.py , accédez à http://127.0.0.1:42069/test.py.
Cliquer pour exécuter des exécutables n'a pas de comportement cohérent sur les distros Linux, il est donc plus facile à installer et à exécuter via la ligne de commande. Selon l'architecture de votre ordinateur, il peut être nécessaire de modifier le nom de fichier à la fin de l'URL de demande curl HTTP ci-dessous.
Voir toutes les options de téléchargement sur la page des versions.
# Download
sudo curl
--location
--output /usr/local/bin/quickserv
https://github.com/jstrieb/quickserv/releases/latest/download/quickserv_linux_x64
# Make executable
sudo chmod +x /usr/local/bin/quickserv
# Make a project folder
mkdir -p /my/project/folder
# Go to project folder
cd /my/project/folder
# Add a test file
cat << EOF > test.py
#!python3
# Put your code here. For example:
import random
print(random.randint(0, 420))
EOF
# Run QuickServ
quickserv Accédez à http://127.0.0.1:42069 (ou à l'adresse indiquée par QuickServ) pour vous connecter à votre application Web. Par exemple, pour exécuter test.py , accédez à http://127.0.0.1:42069/test.py.
Alternativement, utilisez les instructions ci-dessous pour compiler à partir de la source.
Compiler et installer à partir de la source à l'aide de la commande suivante. Une version de GO de plus de 1,16 est requise en raison de la dépendance aux systèmes de fichiers intégrés.
go install github.com/jstrieb/quickserv@latestCréez ensuite votre dossier de projet, remplissez-le et exécutez QuickServ.
# Make a project folder
mkdir -p /my/project/folder
# Go to project folder
cd /my/project/folder
# Add a test file
cat << EOF > test.py
#!python3
# Put your code here. For example:
import random
print(random.randint(0, 420))
EOF
# Run QuickServ
quickservPour démontrer les fonctionnalités clés de QuickServ, nous créerons une application Web simple pour effectuer l'ajout. Le code ne suivra pas les meilleures pratiques, mais il montrera à quel point il est nécessaire de commencer à construire avec QuickServ.
Tout d'abord, nous créons Créer un dossier de projet et fais glisser l'exécutable QuickServ dans le dossier, comme dans les étapes de démarrage.
Ensuite, à l'intérieur du dossier, nous enregistrons le texte suivant en tant index.html :
< form action =" /calculate " >
< input name =" first " type =" number " > + < input name =" second " type =" number " > = ???
< br >
< button > Calculate </ button >
</ form > Ce code soumet deux variables à la page /calculate . Dans le navigateur, cela ressemble à ceci:
Ensuite, nous créons un dossier appelé calculate à l'intérieur du dossier du projet. À l'intérieur du dossier calculate , nous enregistrons le code suivant en tant index.py . Le nom index.whatever ce qui indique à QuickServ pour exécuter ce fichier lorsqu'un utilisateur visite http://website/calculate au lieu de les avoir pour visiter http://website/calculate/index.py .
Portez une attention particulière aux commentaires du code. Ils mettent en évidence un certain nombre de fonctionnalités QuickServ importantes.
#!python3
# Each QuickServ script must begin with a line like the one above so that
# QuickServ knows how to run the file. This line tells QuickServ that I would
# type `python3 this_file.py` to run this file at the command prompt. For
# example, if you wanted to do `julia this_file.py` instead, then you would
# make the first line of `this_file.py` be `#!julia`.
#
# Since we just want QuickServ to show the HTML code to the user and not run
# it, index.html does not begin with this. The first line is only required when
# QuickServ has to run the code.
import argparse
# All HTML form values get turned into command line arguments. The names are
# formatted like "--name" and the value comes right after the name.
parser = argparse . ArgumentParser ()
parser . add_argument ( "--first" , type = int , required = True )
parser . add_argument ( "--second" , type = int , required = True )
args = parser . parse_args ()
# Print the result -- anything printed out goes right to the user. In this
# case, the output is text. But you can print anything and QuickServ will guess
# the file type. Even printing the contents of image and video files works.
print ( args . first + args . second )Maintenant, double-cliquez sur QuickServ dans votre dossier de projet et essayez-le dans votre navigateur. C'est ça!
Voir les exemples liés dans la section suivante pour plus de démonstrations QuickServ. Lisez plus de détails dans la section comment cela fonctionne et dans le code lui-même. La section avancée contient des informations supplémentaires sur l'environnement que QuickServ est en place pour les exécutables qu'il exécute.
Tous les exemples sont situés dans le dossier examples , qui est un sous-module GIT connecté au repo jstrieb / QuickServ-Examples. Accédez à ce dépôt pour plus d'informations sur la façon d'exécuter les exemples.
Quelques points forts:
| Résumé | Langue | Fenêtre | Mac | Linux |
|---|---|---|---|---|
| YouTube à GIF | Coquille | |||
| Créer des filtres Bloom | C | |||
| Liste de films synchronisés | Manuscrit | |||
| Interprète BrainFuck | assemblage x86-64 | |||
| Mandelbrot Zoom | Coquille | |||
| Tableau de bord de crypto-monnaie | Aller | |||
| Outils PDF | Python | |||
| Composé de composition comme PDF | ML standard |
Tout le code QuickServ vit dans quickserv.go . Ce fichier bien vendu dure environ 700 lignes et devrait prendre un programmeur expérimenté sans familiarité de Golang au plus une heure à lire.
QuickServ a deux pièces principales. Le premier est une procédure d'initialisation, exécutez exactement une fois au démarrage. La seconde est une fonction de gestionnaire, appelé chaque fois qu'un utilisateur fait une demande HTTP au serveur.
Lorsque QuickServra le démarrage, il vérifie les indicateurs de configuration de la ligne de commande, ouvre un fichier journal si l'on est passé avec --logfile (sinon il se connecte à la sortie standard) et modifie les répertoires si un répertoire de travail est passé avec --dir . Notez que le chemin du fichier journal est relatif au répertoire de travail actuel, pas par rapport à celui passé avec --dir .
Ensuite, QuickServ analyse le répertoire de travail pour que les fichiers s'exécutent. Il imprime tous les fichiers qui seront exécutés. Ce comportement est utile pour déterminer si QuickServ reconnaît un script comme exécutable. Il imprime également des informations utiles pour l'utilisateur tel que l'adresse Web à visiter pour accéder au serveur, et dans quel dossier le serveur exécute, ainsi que la façon de l'arrêter.
Si une partie de l'initialisation échoue, une erreur est signalée. En cas d'erreur fatale, QuickServ attend la saisie de l'utilisateur avant d'arrêter. De cette façon, un utilisateur qui double-cliquez sur l'exécutable (par opposition à le démarrer à partir de la ligne de commande) n'a pas apparu de fenêtre puis disparaît immédiatement, clignotant trop rapidement pour que l'erreur soit lue.
Les messages d'erreur sont délibérément écrits avec le moins de jargon technique possible, bien que certains soient inévitables. Les causes probables pour les erreurs sont également incluses dans les messages d'erreur, afin qu'ils soient plus faciles à identifier et à corriger les utilisateurs.
En tant que dernière étape de la procédure d'initialisation, QuickServ démarre un serveur Web avec une fonction de gestionnaire unique pour toutes les demandes. Le serveur écoute le port par défaut de 42069 , ou sur un port aléatoire si un utilisateur a spécifié l'indicateur de ligne de commande --random-port . Un port aléatoire serait souhaitable si l'utilisateur doit montrer un projet construit avec QuickServ à quelqu'un sans humour, par exemple.
Lorsqu'un utilisateur visite une page Web, QuickServ géra la demande en appelant la fonction de gestionnaire solitaire.
Tout d'abord, cette fonction essaie d'ouvrir le fichier que l'utilisateur a demandé. S'il ne peut pas trouver ou ouvrir le fichier, il essaie de servir une version par défaut du fichier. Par exemple, il y a un favicon.ico intégré et par défaut qui est servi. S'il n'y a pas de fichier par défaut qui correspond au chemin, il permet à l'erreur GO intégrée de gérer l'erreur et de répondre avec un code d'erreur 404.
Si le fichier que l'utilisateur a demandé est présent, il vérifie s'il s'agit d'un répertoire. S'il s'agit d'un répertoire, QuickServ cherche à l'intérieur d'un fichier nommé index.xxx où xxx est une extension de fichier. Si un fichier d'index est trouvé, l'index est servi (et éventuellement exécuté) comme s'il s'agissait de la page d'origine demandée. Sinon, l'utilisateur doit avoir demandé un répertoire sans index par défaut, donc QuickServ répond avec une liste des autres fichiers dans le répertoire.
Si le fichier que l'utilisateur a demandé est présent et non un répertoire ( c'est-à-dire , il s'agit d'un fichier régulier), QuickServ vérifie s'il est exécutable ou non. Si c'est le cas, il exécute le fichier qu'il a trouvé. Sinon, il renvoie le contenu du fichier brut à l'utilisateur. Dans les deux cas, QuickServra devine le type FileType (et donc quel mimetype ) utiliser pour la réponse.
La technique pour déterminer si un fichier est exécutable dépend du système d'exploitation d'exécution. Sur Windows, tout fichier avec une extension .bat ou .exe est considéré comme exécutable. Sur les systèmes non-Windows, tout fichier avec le jeu de bits d'autorisation exécutable est considéré comme exécutable. Sur tous les systèmes, un fichier est exécutable s'il a un pseudo-shebang valide au début. Le shebang doit être sur la toute première ligne, doit commencer par #! , et doit être une commande valide. Par exemple, les deux suivants sont acceptables, en supposant que python3 est installé et sur le PATH :
#!/usr/bin/python3#!python3 Pour exécuter un fichier, QuickServ exécute le fichier lui-même (s'il s'agit d'un .exe ou a le jeu de bits exécutable), ou il passe le chemin du fichier comme le premier argument à l'exécutable répertorié dans son shebang. Le corps de demande est transmis au programme sur l'entrée standard, et tout ce qui est imprimé par le programme sur la sortie standard est utilisé comme corps de réponse. Les programmes exécutés ne sont ni responsables de l'écriture - ni en mesure d'écrire - les en-têtes de réponse HTTP.
Toutes les variables de formulaire HTTP analysées (si le Content-Type est x-www-form-urlencoded ) sont également passées sous forme d'arguments de ligne de commande lorsque le programme est exécuté. De cette façon, l'utilisateur n'a pas besoin d'analyser les variables elles-mêmes.
Quel que soit le programme exécuté imprime sur l'erreur standard est enregistré par QuickServ, ce qui signifie qu'il est imprimé dans la fenêtre de la console par défaut. C'est pratique pour le débogage. Si le programme se termine avec un code de sortie non nul, QuickServ répond avec une erreur de serveur interne de 500. Sinon, il revient avec un 200.
Si la demande est une demande de poste codée par URL avec des données de formulaire, URL de QuickServ est à décoder tous les caractères à l'exception de trois symboles: % , & , et = . L'utilisateur est responsable de les remplacer. Notez qu'il est important de toujours URL-décode % en dernier dans le programme qui traite les données de formulaire.
Ne pas exécuter QuickServ sur Internet public. Exécutez uniquement sur des réseaux privés.
QuickServ n'est pas conçu pour une utilisation en production. Il n'a pas été créé pour être rapide ou sécurisé. L'utilisation de QuickServ dans la production met vos utilisateurs et vous-même en danger, veuillez ne pas le faire.
QuickServ permet aux gens de construire des choses dangereusement peu sûres. Il ne désinfectue aucune entrée ou sortie. Il utilise un processus par demande et est sensible à une attaque de déni de service. Son modèle de sécurité présume que les utilisateurs Web sont dignes de confiance. Ces caractéristiques facilitent le prototypage, mais ne sont pas en sécurité sur Internet public.
Pour dissuader l'utilisation de QuickServ en production, il fonctionne sur le port 42069 . Espérons que cela ferait réfléchir à tout le monde avant de l'entrer dans un proxy inversé ou une configuration de transfert de port. Pour une démo plus professionnelle, l'indicateur de ligne de commande --random-port utilisera plutôt un port aléatoire, déterminé à l'exécution.
QuickServ est similaire à l'ancien protocole CGI. Il existe de nombreuses raisons bien articulées et bien établies que CGI est mauvaise en production, et ils s'appliquent tous à QuickServ en production.
QuickServ a des options avancées configurées via des drapeaux de ligne de commande. Ceux-ci changent comment et où QuickServ fonctionne, ainsi que l'endroit où il sauve sa sortie.
Usage:
quickserv [options]
Options:
--dir string
Folder to serve files from. (default ".")
--logfile string
Log file path. Stdout if unspecified. (default "-")
--no-pause
Don't pause before exiting after fatal error.
--random-port
Use a random port instead of 42069.
Dans l'imitation de CGI, les en-têtes HTTP sont transmis au programme exécuté en tant que variables d'environnement. Un en-tête appelé Header-Name sera défini comme la variable d'environnement HTTP_HEADER_NAME .
Il existe également une variable REQUEST_TYPE qui spécifie si la demande était GET , POST , etc.
Les demandes HTTP avec un corps passent le corps au programme exécuté sur l'entrée standard. Dans la plupart des cas, le corps de demande est adopté textuellement. Ce n'est pas le cas pour les formulaires HTML.
Les données du formulaire HTML peuvent être lues à partir des arguments de ligne de commande, comme dans le tutoriel, soit analysés à partir de l'entrée standard. Les variables prennent la forme
name=value&othername=othervalue
L'exemple d'ajout simple du tutoriel peut être réécrit pour analyser les valeurs de formulaire HTTP à partir de l'entrée standard plutôt que des arguments de ligne de commande.
#!python3
import sys
# In the form input, "=" and "&" determine where variables start and end. So if
# they are literally included in the variable name or value, they must be
# specially decoded. This code replaces every instance of the text on the left
# with the text on the right to do the decoding:
# %3D -> =
# %26 -> &
# %25 -> %
#
# NOTE: Order matters! "%" must be decoded last. If not, it can mess with
# decoding the others, since their encoded version uses "%"
def decode_characters ( text ):
text = text . replace ( "%3D" , "=" )
text = text . replace ( "%26" , "&" )
text = text . replace ( "%25" , "%" )
return text
first = second = 0
# Read all of the input into a variable. We are expecting the raw data to look
# like:
# first=123&second=456
data = sys . stdin . read ()
# The raw data looks like the above, so split it into pairs at each "&"
pairs = data . split ( "&" )
for pair in pairs :
# Each pair looks like the following, so split at each "=":
# name=value
name , value = pair . split ( "=" )
# Decode any special characters (=, &, %) now that we have split the
# variables up. This isn't necessary here since we're expecting numbers and
# not expecting any of those characters. But it matters a lot when a user
# could submit text with those characters
name = decode_characters ( name )
value = decode_characters ( value )
# If the name is what we're looking for, store the value for adding
if name == "first" :
first = int ( value )
elif name == "second" :
second = int ( value )
# Print the result -- anything printed out goes right to the user. In this
# case, the output is text. But you can print anything and QuickServ will try and
# guess the file type.
print ( first + second )Ce projet est activement développé et maintenu. S'il n'y a pas de commits récents, cela signifie que tout fonctionne bien!
Veuillez ouvrir un problème avec tous les bogues, suggestions ou questions. Cela comprend particulièrement les discussions sur la façon de rendre les messages d'erreur aussi clairs que possible, et comment rendre les paramètres par défaut applicables à autant d'utilisateurs que possible.
Les demandes de traction sans discussion préalables seront ignorées - ne perdez pas de temps à écrire du code avant de confirmer qu'il sera fusionné. En tant que développeur occupé et seul, il est plus réactif lorsque toutes les contributions du code ont un contexte.
Si vous créez un article de blog, une vidéo, un tutoriel, un projet de hackathon ou quoi que ce soit en utilisant QuickServ, veuillez ouvrir un problème ou m'envoyer un message sur mon formulaire de contact afin que je puisse vous connecter!
Il existe plusieurs façons de soutenir le projet:
Ces choses me motivent à continuer de partager ce que je construis, et elles fournissent une validation que mon travail est apprécié! Ils m'aident également à améliorer le projet. Merci d'avance!
Si vous insistez pour dépenser de l'argent pour montrer votre soutien, je vous encourage à faire un généreux don à l'une des organisations suivantes. En plaidant pour les libertés sur Internet, des organisations comme celles-ci m'aident à me sentir à l'aise de publier du travail publiquement sur le Web.
Ce projet ne serait pas possible sans l'aide de:
