---
title: "Sperimentare con Varlink: Creare un Servizio IPC Hello World"
date: 2025-12-03
description: >
  Un tutorial pratico che esplora Varlink come meccanismo moderno di IPC. Costruiamo un semplice servizio hello world in Rust e discutiamo perché Varlink potrebbe diventare la spina dorsale della comunicazione interna tra macchine in DownToZero.
---

Se hai mai provato a far comunicare diversi processi su un sistema Linux in modo efficiente, sai che il panorama è... diciamo, frammentato. Abbiamo D-Bus, socket Unix con protocolli personalizzati, REST API su localhost, gRPC e innumerevoli altri approcci. Ognuno con la sua complessità, requisiti di strumenti e curva di apprendimento.

Di recente, mi sono imbattuto in [Varlink](https://varlink.org/) (e nel suo fratello più moderno incentrato su Rust, [Zlink](https://github.com/z-galaxy/zlink)), e ha immediatamente fatto clic con ciò che stiamo cercando di realizzare in DownToZero. Stiamo costruendo un'infrastruttura che necessita di una comunicazione inter-processo affidabile e a basso overhead - dall'orchestrazione di container alla gestione delle impostazioni delle macchine. Più approfondivo Varlink, più mi sono reso conto che potrebbe essere esattamente ciò di cui abbiamo bisogno.

In questo post, ti guiderò attraverso i miei esperimenti con Varlink. Costruiremo insieme un semplice servizio hello world, passo passo, e condividerò le mie riflessioni sul perché questa tecnologia mi entusiasma per il futuro della nostra piattaforma.

## Cos'è Varlink e Perché Dovresti Interessartene?

Varlink è un formato di descrizione dell'interfaccia e un protocollo progettati per definire e implementare interfacce di servizio. Pensalo come un'alternativa più semplice e moderna a D-Bus, o un'alternativa più leggera a gRPC per la comunicazione locale.

Se hai lavorato con D-Bus in passato, probabilmente conosci il dolore: sistemi di tipi complessi, introspezione che richiede strumenti speciali, file di configurazione XML che sembrano fatti per confondere. D-Bus è potente, ma risale a un'epoca in cui "semplice" non era una priorità progettuale. Varlink adotta un approccio diverso - è quello che D-Bus potrebbe sembrare se fosse progettato oggi, con sensibilità moderne sull'esperienza dello sviluppatore.

Ecco cosa rende Varlink interessante:

1. **Interfacce autodocumentate**: Ogni servizio Varlink può descrivere la propria API. Puoi connetterti a qualsiasi servizio e chiedere "cosa puoi fare?" e ottenere una risposta leggibile dalla macchina (e anche dall'umano).

2. **Indipendente dal linguaggio**: Il protocollo è semplice al punto che esistono implementazioni in Rust, Go, Python, C, e altro ancora. Ma soprattutto, le interfacce stesse sono neutrali rispetto al linguaggio.

3. **Basato su socket**: La comunicazione avviene tramite socket Unix (o TCP per connessioni remote), il che significa che si integra bene con l’ecosistema Linux, i container e systemd.

4. **Protocollo basato su JSON**: Il formato di trasmissione è JSON, che rende il debug banale. Puoi letteralmente usare `netcat` per parlare con un servizio Varlink, se vuoi.

5. **Integrazione con systemd**: Questo è enorme. systemd usa già Varlink per alcuni dei suoi servizi interni, il che significa che il protocollo è collaudato e ha supporto nativo per l'attivazione tramite socket e la gestione dei servizi.

## Perché Varlink per DownToZero?

In DTZ, ci occupiamo costantemente della configurazione e orchestrazione a livello macchina. La nostra infrastruttura spazia dall'hardware fisico (potresti ricordare i nostri [nodi alimentati a energia solare](/posts/2024/physical-location)), ai container, ai vari servizi di sistema che devono coordinarsi.

Attualmente, abbiamo un mix di approcci per la comunicazione inter-processo:
- API REST per servizi rivolti all'esterno
- Chiamate dirette di funzione all'interno dei nostri servizi Rust
- Alcuni protocolli basati su socket ad-hoc per casi d'uso specifici

Quello che ci manca è un modo unificato per far comunicare i nostri servizi a livello di sistema. Considera questi scenari:

- Un servizio container deve interrogare i limiti di risorse dell'host
- I nostri agenti di osservabilità devono comunicare con i demoni di monitoraggio di sistema
- Le modifiche di configurazione devono propagarsi tra più servizi locali
- I controlli di salute del sistema devono aggregare dati da vari sottosistemi

Per tutti questi casi, Varlink offre una soluzione convincente. È locale prima di tutto (ottimo per la latenza), autodocumentante (ottimo per il debug), e ha supporto nativo systemd (ottimo per l'affidabilità).

Il fatto che systemd stesso usi Varlink per servizi come `systemd-resolved` e `systemd-hostnamed` significa che potremmo potenzialmente integrarci direttamente con i servizi di sistema usando lo stesso protocollo che usiamo per i nostri. È potente.

## Costruiamo Qualcosa: Un Servizio Hello World

Basta teoria - mettiamoci all'opera. Ho creato una semplice implementazione hello world per testare il terreno, e ti guiderò nella costruzione da zero.

Il codice sorgente completo è disponibile su [https://github.com/DownToZero-Cloud/varlink-helloworld](https://github.com/DownToZero-Cloud/varlink-helloworld).

### Passo 1: Creare il Progetto

Per prima cosa, crea un nuovo progetto Rust:

```bash
cargo new varlink-helloworld
cd varlink-helloworld

[package]
name = "varlink-helloworld"
version = "0.1.0"
edition = "2024"

[dependencies]
futures-util = "0.3"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }
zlink = { version = "0.2" }

use serde::{Deserialize, Serialize};
use zlink::{
    self, Call, Connection, ReplyError, Server, Service, 
    connection::Socket, service::MethodReply,
    unix, varlink_service::Info,
};

const SOCKET_PATH: &str = "/tmp/hello.varlink";

#[tokio::main]
async fn main() {
    println!("starting varlink hello world server");
    run_server().await;
}

pub async fn run_server() {
    // Pulisce eventuali file socket esistenti
    let _ = tokio::fs::remove_file(SOCKET_PATH).await;
    
    // Lega al socket Unix
    let listener = unix::bind(SOCKET_PATH).unwrap();
    
    // Crea il nostro servizio e il server
    let service = HelloWorld {};
    let server = Server::new(listener, service);

    match server.run().await {
        Ok(_) => println!("server done."),
        Err(e) => println!("server error: {:?}", e),
    }
}

#[derive(Debug, Deserialize)]
#[serde(tag = "method")]
enum HelloWorldMethod {
    #[serde(rename = "rocks.dtz.HelloWorld.Hello")]
    Hello,
    #[serde(rename = "rocks.dtz.HelloWorld.NamedHello")]
    NamedHello {
        #[serde(default)]
        parameters: NamedHelloParameters,
    },
    #[serde(rename = "org.varlink.service.GetInfo")]
    VarlinkGetInfo,
}

#[derive(Debug, Serialize, Deserialize, Default)]
pub struct NamedHelloParameters {
    name: String,
}

#[derive(Debug, Serialize)]
#[serde(untagged)]
enum HelloWorldReply {
    Hello(HelloResponse),
    VarlinkInfo(Info<'static>),
}

#[derive(Debug, Serialize)]
pub struct HelloResponse {
    message: String,
}

#[derive(Debug, ReplyError)]
#[zlink(interface = "rocks.dtz.HelloWorld")]
enum HelloWorldError {
    Error { message: String },
}

struct HelloWorld {}

impl Service for HelloWorld {
    type MethodCall<'de> = HelloWorldMethod;
    type ReplyParams<'ser> = HelloWorldReply;
    type ReplyStreamParams = ();
    type ReplyStream = futures_util::stream::Empty<zlink::Reply<()>>;
    type ReplyError<'ser> = HelloWorldError;

    async fn handle<'ser, 'de: 'ser, Sock: Socket>(
        &'ser mut self,
        call: Call<Self::MethodCall<'de>>,
        _conn: &mut Connection<Sock>,
    ) -> MethodReply<Self::ReplyParams<'ser>, Self::ReplyStream, Self::ReplyError<'ser>> {
        println!("handling call: {:?}", call.method());
        match call.method() {
            HelloWorldMethod::Hello => {
                MethodReply::Single(Some(HelloWorldReply::Hello(HelloResponse {
                    message: "Hello, World!".to_string(),
                })))
            }
            HelloWorldMethod::NamedHello { parameters } => {
                MethodReply::Single(Some(HelloWorldReply::Hello(HelloResponse {
                    message: format!("Hello, {}!", parameters.name),
                })))
            }
            HelloWorldMethod::VarlinkGetInfo => {
                MethodReply::Single(Some(HelloWorldReply::VarlinkInfo(Info::<'static> {
                    vendor: "DownToZero",
                    product: "hello-world",
                    url: "https://github.com/DownToZero-Cloud/varlink-helloworld",
                    interfaces: vec!["rocks.dtz.HelloWorld", "org.varlink.service"],
                    version: "1.0.0",
                })))
            }
        }
    }
}

cargo run

varlinkctl info /tmp/hello.varlink

varlinkctl call /tmp/hello.varlink rocks.dtz.HelloWorld.Hello {}

{
    "message" : "Hello, World!"
}

varlinkctl call /tmp/hello.varlink rocks.dtz.HelloWorld.NamedHello '{"name":"jens"}'

{
    "message" : "Hello, jens!"
}

echo '{"method":"rocks.dtz.HelloWorld.Hello","parameters":{}}' | \
  socat - UNIX-CONNECT:/tmp/hello.varlink

varlinkctl introspect /tmp/hello.varlink rocks.dtz.HelloWorld

[Unit]
Description=Hello World Varlink Socket

[Socket]
ListenStream=/run/hello.varlink

[Install]
WantedBy=sockets.target

[Unit]
Description=Hello World Varlink Service

[Service]
ExecStart=/usr/local/bin/varlink-helloworld