fezz

A single Rust-based Host HTTP Runtime (HHRF) runs lightweight "fetch-like" Fezz function modules using a load-run-unload execution model, providing a serverless-style platform.

Demo

1. Build sample function and runner

cargo build --release -p example_todosapi -p hhrf

2. Fonksiyon kütüphanesini functions klasörüne koy

# org/func/version formatında dizin oluştur
mkdir -p ./functions/acme/todos/0.0.1
cp target/release/libexample_todosapi.dylib ./functions/acme/todos/0.0.1/fezz.so

İsterseniz .env dosyası da ekleyebilirsiniz:

echo "EXAMPLE_VAR=demo" > ./functions/acme/todos/0.0.1/.env

3. HHRF server'ını çalıştır

export HHRF_ROOT=.
cargo run -p hhrf --release

4. Fonksiyonu test et

curl http://127.0.0.1:3000/rpc/acme/todos/0.0.1/hello

5. JS embed demo (fezz.js)

cat <<'EOF' > ./functions/acme/todos/0.0.1/fezz.js
export default {
  async fetch(request, env, ctx) {
    return new Response(`ok: ${request.method} ${request.path}`);
  },
};
EOF

curl "http://127.0.0.1:3000/js-embed/acme/todos/0.0.1/hello?x=1"

Runner'ı Jail ile Sarmak

HHRF, kullanacağı runner binary'sini FEZZ_RUNNER ortam değişkeni ile ayarlamana izin verir:

• Varsayılan: FEZZ_RUNNER tanımlı değilse fezz-runner kullanılır.
• Prod ortamda Linux üzerinde, FEZZ_RUNNER'ı bir jailer ile wrap edebilirsin (ör. nsjail, firejail, bwrap).

Örnek (konsept):

export FEZZ_RUNNER=/usr/local/bin/nsjail-fezz-runner

nsjail-fezz-runner script/bin'i içinde:

• Low-priv user'a geç,
• Gerekirse chroot / namespace / seccomp ayarlarını yap,
• Sonra gerçek fezz-runner'ı bu sandbox içinde çalıştır.

Panic Safety

#[fezz_function] macro'su, user fonksiyonunu std::panic::catch_unwind ile saran bir fezz_handle_v2 FFI entrypoint'i üretir. Böylece user kodundaki panikler FFI boundary'yi geçmez, HTTP 500 dönen structured error response'a çevrilir.

Async Runtime Isolation

fezz_handle_v2 exported C fonksiyonu senkron çalışır. Fonksiyon içinde HTTP/Redis gibi işler için bloklayan client'lar kullanılır. HHRF tarafında çağrı artık ayrı bir process olduğu için host async runtime'ı bloklanmaz; ek olarak process-level izolasyon kazanılır.

Best Practices for User Functions

State and Caching

Artık her çağrı ayrı bir process içinde olsa bile (özellikle fezz-runner modeliyle), fonksiyon kütüphanesi birden çok kez reuse edilebilir. Ağır client'lar için yine std::sync::OnceLock gibi mekanizmaları kullanabilirsin, ancak unutmaman gereken nokta:

• Process crash ederse (panic, segfault), sonraki çağrı yeni bir process ile sıfırdan başlar.
• Bu nedenle state'i sadece performans için kullan, doğruluk için değil.

Guidelines

1. Blocking client kullan: FFI interface senkron olduğu için HTTP/DB için bloklayan client'lar en sade yol.
2. Panik yerine hata döndür: Panik etmek yerine FezzWireResponse ile düzgün hata mesajları dön.
3. Stateless tasarla: İş mantığını her request bağımsız olacak şekilde yaz; global mutable state'e güvenme.
4. Timeout'ları düşün: Dış servis çağrılarına makul timeout'lar koy; child process askıda kalmasın.