capy.network v0.5.4

capy à travers tout internet. Une machine chez toi est cachée derrière ta box : personne ne peut la joindre directement depuis l'extérieur. capy.network contourne ça avec un relais, un petit programme qui tourne sur une machine joignable depuis internet (un VPS, un serveur loué quelques euros par mois).

Comment ça marche#

Le serveur (chez toi) se connecte au relais et y reste branché, sous un nom. Le client (n'importe où) demande au relais de transmettre son appel à ce nom. Le relais fait passer la demande et la réponse.

 client (n'importe où)          relais (VPS)               serveur (chez toi, derrière la box)
        │                            │                                 │
        │                            │ ◄──── se connecte : « maison » ─┤
        ├── call("maison", "test") ─►│                                 │
        │                            ├──── {"action": "test"} ────────►│
        │                            │◄─── {"text": "Hello"} ──────────┤
        │◄─── {"text": "Hello"} ─────┤                                 │

Comme c'est le serveur qui appelle le relais, aucun port à ouvrir sur ta box. Seul le VPS doit avoir un port ouvert. Tout est chiffré de bout en bout jusqu'au relais, et le relais demande une clé (un mot de passe).

Mettre en place le relais#

Sur le VPS (Linux), une seule fois :

1. Installe capy : python3 -m pip install --user capyy.
2. Choisis une clé longue et aléatoire (voir l'astuce juste en dessous).
3. Ouvre le port dans le pare-feu : sudo ufw allow 3879/tcp.
4. Lance le relais, et note l'empreinte qu'il affiche (si capy n'est pas trouvé sur le VPS : python3 -m capy.network 3879 …).

capy relay 3879 MA_CLE_SECRETE

Relais capy.network en écoute sur le port 3879, chiffré (TLS), avec clé
Empreinte : 9b734c758696262e758f8664db40fafe3601f3804ced5dc331527704319f3049

Le serveur (chez toi)#

import capy.network

capy.network.use("mon-vps.fr:3879", key="MA_CLE_SECRETE")

api = capy.network.Server("maison")

@api.action("test")
def test():
    return {"text": "Hello"}

api.run()   # se reconnecte tout seul si le relais redémarre ou si internet coupe

Connecté au relais mon-vps.fr:3879 sous le nom 'maison' (chiffré)
réseau → {"action": "test"}

Le client (n'importe où)#

import capy
import capy.network

capy.network.use(
    "mon-vps.fr:3879",
    key="MA_CLE_SECRETE",
    fingerprint="9b734c758696262e758f8664db40fafe3601f3804ced5dc331527704319f3049",
)

try:
    reponse = capy.network.call("maison", "test")
except ConnectionError as e:
    exit(str(e))

print(capy.get(reponse, "text"))

Hello

Depuis le terminal#

capy network call maison test --relay mon-vps.fr:3879 --key "$CAPY_KEY"

{
  "text": "Hello"
}

• Le relais et la clé peuvent venir d'ailleurs que des options : du capy.config.json du dossier (mode network), ou des variables d'environnement CAPY_RELAY et CAPY_KEY. Avec export CAPY_RELAY=mon-vps.fr:3879 dans ~/.zshrc, c'est juste capy network call maison test.
• --fingerprint … vérifie l'empreinte du relais dès le 1er appel.
• Lancer un relais : capy network relay 3879 CLÉ, ou plus court capy relay 3879 CLÉ.
• Dans un projet en mode network, cy call test passe par le relais de capy.config.json.

Les erreurs#

Rapidité#

• Le 1er appel ouvre la connexion chiffrée vers le relais : environ 1 s vers un VPS lointain.
• Les suivants réutilisent cette connexion : environ un aller-retour (≈ 200 ms) + le trajet relais → serveur.
• Plusieurs appels en parallèle (depuis plusieurs threads) passent par la même connexion, sans se gêner.
• Le relais attend la réponse du serveur 10 s au maximum.

Garder le relais allumé#

Lancé dans un terminal ssh, le relais s'arrête quand tu fermes la session. Pour qu'il tourne toujours et redémarre tout seul (même après un redémarrage du VPS), fais-en un service systemd : voir l'exemple « Garder le relais allumé (systemd) » plus bas.

Astuces et pièges#