Documentation on vanityURLs

Analytics serveur

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs enregistre les analytics depuis le Worker, pas depuis du JavaScript navigateur. Les redirections peuvent etre mesurees meme quand le visiteur ne charge jamais de page HTML, et les pages publiques n’ont pas besoin de script de tracking client.

Les analytics sont non bloquants. Le Worker envoie les evenements avec ctx.waitUntil(), donc la latence des redirections ne depend pas de la disponibilite de Umami, Fathom, ou autre fournisseur.

Fournisseurs

Definissez un ou plusieurs fournisseurs avec ANALYTICS_PROVIDER :

Approche securite du runtime

Mon, 01 Jan 0001 00:00:00 +0000

Le runtime vanityURLs est volontairement simple. Ce n’est pas un service public de soumission de liens, pas une application avec base de donnees, et pas un framework web generaliste. C’est un moteur de redirection construit depuis Git : valider le registre, deployer les assets statiques, lire v8s.json, puis retourner un petit nombre de resultats possibles.

La simplicite fait partie du modele de securite. Le Worker a moins de pieces mobiles qu’un raccourcisseur classique : pas d’API d’ecriture publique, pas de comptes visiteurs, pas de cookies, pas d’analytics cote client, pas de couche de requete base de donnees, et pas de serveur d’origine derriere Cloudflare.

Checklist de release

Mon, 01 Jan 0001 00:00:00 +0000

Utilisez cette checklist avant de lancer une nouvelle instance ou de promouvoir une mise a jour majeure. Une instance v8s est simple, mais un domaine court attire quand meme scanners, bots, et tentatives d’abus.

Depot

Lancez npm run clean.
Rafraichissez defaults/ et scripts/ upstream avec le workflow de mise a jour.
Gardez tous les fichiers propres a l’instance dans custom/.
Lancez npm run check.
Relisez les changements de registre genere et de blocklist.
Commitez et deployez depuis un working tree propre.

Worker et assets

Confirmez que le Worker a un binding ASSETS.
Confirmez que le domaine custom pointe vers le Worker.
Desactivez les URL publiques workers.dev et preview si elles ne font pas partie du service.
Protegez /_stats et /_tests avec Cloudflare Access.
Gardez les politiques /_stats/* et /_tests/* etroites.
Confirmez que le Worker accepte seulement GET, HEAD, et OPTIONS.
Confirmez que les assets d’implementation prives retournent 404.

Configuration domaine Cloudflare

Dans Cloudflare, les reglages pertinents sont repartis dans trois endroits :

CLI

Mon, 01 Jan 0001 00:00:00 +0000

La CLI locale au depot est ./scripts/lnk. C’est un executable Node, donc il fonctionne sur macOS, Linux, Windows, et les environnements CI ou Node et Git sont disponibles.

Bash n’est pas requis pour gerer les liens. Le helper Zsh reste optionnel et separe.

Prerequis

Node.js 20 ou plus recent
npm
Git
Wrangler pour les commandes de deploiement
Un compte Cloudflare seulement pour deployer ou gerer les secrets Worker

Sur Windows, lancez les commandes depuis PowerShell, Windows Terminal, ou un shell qui voit Git. La CLI ne demande pas WSL.

Cloudflare Workers

Mon, 01 Jan 0001 00:00:00 +0000

Le runtime vanityURLs actuel se deploie comme Worker Cloudflare avec assets statiques. Le Worker est l’origine du domaine court, donc utilisez un Custom Domain Worker plutot que l’ancien modele Pages _redirects ou DNS AAAA 100::.

Cloudflare repartit les reglages necessaires a vanityURLs dans trois zones differentes du dashboard. Verifiez le scope du dashboard avant de modifier un reglage; etre dans le bon produit Cloudflare ne suffit pas toujours.

Demarrage rapide

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs est un moteur de liens courts gere dans Git pour votre propre domaine. Le runtime actuel se deploie comme Worker Cloudflare avec assets statiques. Le build part de defaults/, applique vos fichiers custom/, genere build/v8s.json, puis publie le Worker avec Wrangler.

Prerequis

Un depot GitHub base sur vanityURLs/vanityURLs
Un domaine court, comme le domaine public de reference v8s.link
Un compte Cloudflare avec le domaine dans Cloudflare DNS
Node.js 20 ou plus recent et npm
Git
Wrangler connecte au compte Cloudflare qui possede le Worker

La CLI principale est ./scripts/lnk, un script Node qui tourne sur macOS, Linux, Windows, et les environnements CI ou Node et Git sont disponibles. Bash n’est pas requis pour gerer les liens, planifications, ou blocklists. Le helper optionnel scripts/v8s.zsh sert seulement aux utilisateurs Zsh qui veulent ouvrir des redirections connues depuis leur shell.

Format des liens

Mon, 01 Jan 0001 00:00:00 +0000

v8s-links.txt est la source de verite humaine pour les liens. Chaque ligne non vide et non commentee est separee par des pipes :

slug|target|state|title|description|tags|owner|expires_at|notes

Champ	Requis	Description
`slug`	oui	Chemin sans `/` initial
`target`	oui	URL `http` ou `https`, ou hostname normalise vers `https://`
`state`	non	`permanent`, `ephemeral`, `expired`, `disabled`, `maintenance`, `deactivated`
`title`	non	Titre pour le dashboard
`description`	non	Usage humain du lien
`tags`	non	Tags separes par virgules
`owner`	recommande	Etiquette de responsabilite
`expires_at`	non	Date ou timestamp ISO
`notes`	non	Notes internes

Liens exacts

social/x|https://x.com/vanityURLs|permanent|X / Twitter|Profil social|social,x|v8s||

Le lien resout seulement /social/x.

Guide de migration

Mon, 01 Jan 0001 00:00:00 +0000

Utilisez ce guide pour passer de l’ancien modele Cloudflare Pages _redirects au modele Worker actuel utilise par v8s.link.

Ce qui a change

wrangler.toml est la source de verite du deploiement
Les fichiers statiques sont servis via le binding Worker ASSETS
Le build copie defaults/, applique custom/, et genere build/v8s.json
custom/v8s-links.txt est prefere quand il existe; sinon le build utilise defaults/v8s-links.txt
/_stats et /_tests sont proteges par Cloudflare Access
Les analytics serveur sont emis par le Worker
Les probes et destinations risquees sont bloquees par v8s-blocklist.json

Convertir les anciens fichiers .lnk

Les anciennes lignes ressemblaient a ceci :

Liens planifies

Mon, 01 Jan 0001 00:00:00 +0000

Les liens planifies permettent a un slug stable de pointer ailleurs pendant certaines plages horaires. Gardez le lien normal dans v8s-links.txt, puis ajoutez les regles dans v8s-schedules.json.

Les planifications s’appliquent actuellement aux liens exacts. Les liens splat restent bases sur le chemin.

Pour les changements courants, utilisez la CLI Node au lieu de modifier le JSON a la main :

./scripts/lnk schedule add hangout https://zoom.us/j/work --label work --days mon,tue,wed,thu,fri --from 09:00 --to 17:00 --timezone America/Toronto --default https://discord.gg/personal
./scripts/lnk schedule list hangout

La CLI ecrit custom/v8s-schedules.json par defaut. Definissez V8S_SCHEDULES_FILE ou passez --file pour utiliser un autre chemin.

Mettre a jour une instance

Mon, 01 Jan 0001 00:00:00 +0000

Installer une instance vanityURLs est facile. La mettre a jour proprement demande un workflow reproductible, parce que le proprietaire doit garder ses liens, sa marque, sa politique et sa configuration Cloudflare tout en recevant les nouveaux defaults, scripts, correctifs et durcissements securite.

La regle est simple :

les fichiers propres a l’instance vivent dans custom/
les reglages de deploiement Cloudflare vivent dans wrangler.toml
la sortie generee est jetable
les fichiers produit upstream vivent dans defaults/ et scripts/

Commande d’upgrade

Lancez depuis un worktree propre :

Politique blocklist

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs utilise defaults/v8s-blocklist.json comme politique anti-abus upstream. La politique propre a l’instance vit dans custom/v8s-blocklist.json et surcharge les defaults.

L’objectif est de proteger la reputation d’un domaine court en reduisant phishing, malware, chaines de redirection, et formes d’URL risquees.

Un redirecteur est une infrastructure puissante. N’utilisez pas une instance vanityURLs pour cacher des destinations malveillantes, contourner des systemes de confiance, blanchir une chaine d’autres raccourcisseurs, dissimuler des liens affiliés ou de tracking sans divulgation, ou envoyer les gens vers du contenu qu’ils ne pouvaient pas raisonnablement attendre. Un domaine court gagne la confiance lentement et peut la perdre tres vite.

Registre runtime

Mon, 01 Jan 0001 00:00:00 +0000

Le Worker ne lit pas v8s-links.txt a chaque requete. Le build cree un registre runtime prive dans build/v8s.json et le publie comme asset interne. Les requetes publiques directes vers v8s.json, redirect-targets.json, et les assets de blocklist retournent 404.

Le registre est volontairement simple : un fichier JSON genere, schema version 2.2, valide avant deploiement, consomme par un seul Worker.

Entrees du build

Le registre est genere a partir de :

defaults/v8s-links.txt, puis custom/v8s-links.txt
defaults/v8s-schedules.json, puis custom/v8s-schedules.json
defaults/v8s-blocklist.json, les donnees blocklist generees, et custom/v8s-blocklist.json
les assets statiques de defaults/public/, surcharges par custom/public/

Utilisez custom/ pour chaque changement propre a une instance. Les mises a jour futures restent simples : upstream peut rafraichir defaults/ et scripts/, pendant que l’instance garde ses liens, sa politique, son habillage, ses pages legales, et ses secrets generes.

Structure du depot

Mon, 01 Jan 0001 00:00:00 +0000

Le depot separe les defaults du produit des changements propres a une instance. Cette separation rend v8s.link utile comme implementation de reference et permet de mettre a jour le code upstream sans perdre la marque locale.

defaults/
 public/ # HTML, CSS, icones et pages localisees par defaut
 public/_stats/ # shell du tableau stats en lecture seule
 v8s-links.txt # registre demo/par defaut
 v8s-schedules.json # regles de planification optionnelles
 v8s-blocklist.json # politique anti-abus par defaut
 v8s-blocklist-categories.json

custom/
 public/ # marque et pages propres a l'instance
 v8s-links.txt # liens de l'instance
 v8s-schedules.json # planifications de l'instance
 v8s-blocklist.json # politique locale allow/block

scripts/
 src/
 worker.mjs # source canonique du Worker runtime
 worker.test.mjs # tests du Worker runtime
 lnk # CLI Node pour liens et planifications
 build.mjs # build defaults + custom vers la sortie deploy
 clean.mjs # supprime la sortie generee
 upgrade.mjs # rafraichit les fichiers produit depuis upstream

build/
 v8s.json # registre runtime genere
 v8s-blocklist.json # politique anti-abus generee
 ...assets statiques...

Defaults

defaults/ est la base du produit. L’instance publique v8s.link utilise ces fichiers pour montrer un raccourcisseur fonctionnel avec page d’accueil de recherche, page expand, pages d’etat localisees, icones, shell stats protege, et liens exemples.

Surcharges custom

Mon, 01 Jan 0001 00:00:00 +0000

Utilisez custom/ pour les fichiers propres a l’instance. Cela garde les deploiements de type v8s.link faciles a mettre a jour, car les pages par defaut, la logique Worker et les politiques produit peuvent evoluer sans melanger tous les choix de marque locaux.

Ordre de build

Copier defaults/public/ dans build/
Appliquer custom/public/ s’il existe
Copier defaults/public/_stats/index.html
Appliquer custom/public/_stats/index.html s’il existe
Construire v8s.json depuis custom/v8s-links.txt s’il existe, sinon depuis defaults/v8s-links.txt
Fusionner defaults/v8s-blocklist.json, custom/v8s-blocklist.json optionnel, et les donnees de blocklist generees

Fichiers custom recommandes

custom/v8s-links.txt
custom/v8s-schedules.json
custom/v8s-blocklist.json
custom/public/v8s-logo.svg
custom/public/v8s-redirected.svg
custom/public/favicon.svg

Ajoutez des surcharges HTML ou CSS seulement quand les assets de marque et les fichiers de contenu ne suffisent pas.

Tableau admin

Mon, 01 Jan 0001 00:00:00 +0000

Le tableau admin est volontairement en lecture seule. C’est une vue operationnelle du registre genere, pas un CMS.

Il lit :

/v8s.json

Ce qu’il montre

Inventaire des routes
Etat effectif
Routage exact vs splat
Revue des expirations
Qualite des metadonnees
Comportement de la table de routage
Filtres expire bientot et metadata manquante

Les analytics restent dans Umami ou Fathom. Le dashboard est le plan routage et cycle de vie; les outils analytics sont le plan mesure.

Validation et CI

Mon, 01 Jan 0001 00:00:00 +0000

Lancez la validation avant chaque deploiement. v8s est concu pour que les erreurs de liens, les cibles dangereuses, les assets generes perimes, et les regressions Worker echouent avant qu’une nouvelle version arrive sur Cloudflare.

Commandes locales

Utilisez le controle combine pour le travail normal :

npm run check

Il construit le runtime, lance le lint, et execute les tests Worker. Pour un travail cible, utilisez :

npm run lint
npm test
npm run build
npm run smoke:analytics

Lancez npm run clean avant une release ou avant de comparer la sortie generee. Cela retire le cruft de build pour que le depot montre seulement les changements source intentionnels.

Documentation on vanityURLs

Analytics serveur

Fournisseurs

Approche securite du runtime

Checklist de release

Depot

Worker et assets

Configuration domaine Cloudflare

CLI

Prerequis

Cloudflare Workers

Carte de navigation Cloudflare

Demarrage rapide

Prerequis

Format des liens

Liens exacts

Guide de migration

Ce qui a change

Convertir les anciens fichiers .lnk

Liens planifies

Mettre a jour une instance

Commande d’upgrade

Politique blocklist

Registre runtime

Entrees du build

Structure du depot

Defaults

Surcharges custom

Ordre de build

Fichiers custom recommandes

Tableau admin

Ce qu’il montre

Validation et CI

Commandes locales