Burak Selim Şenyurt

Testler için Bir Mail Sunucusu Yazmak

2026-09-07T10:52:00+00:00

Uzun zaman önce Friday Night Programmer laboratuvarında bir e-posta sunucusuna ihtiyacım oldu. Amacım, belli bir sürecin entegrasyon testleri sırasında bir e-posta sunucusuna gidip gelme aksiyonunu taklit etmekti. İhtiyacım olan entegrasyon testi, ortamda gerçek bir e-posta sunucusu olmadan da çalışabilmeliydi. Nitekim asıl odak noktam e-postaların gidip gitmemesi değildi. Sürecin bir parçası olarak ilgili e-postalar gitmiş ve sunucudan olumlu cevap almışım(ya da almamışım) gibi hareket etmek istiyordum. Pekala, bu konuda yazılmış çeşitli sahte(fake) sunucular olabilirdi ama bana hafif sıklet bir aparat gerekiyordu. Aklıma Rust ve bu tip sunucu bazlı işlemlerde öne çıkan tokio küfesi(crate) geldi. Sonuçta bir sunucu, belli bir port üzerinden gelen mesajları yakalayıp şakacıktan karşı tarafa gönderdim gibi yapsa yeterliydi. Bu yazıdaki amacım, örnek kodlar üzerinden geçerek kendime ve sizlere hatırlatıcı noktalar çıkarmak olacak. Öyleyse gelin vakit kaybetmeden başlayalım.

Mail Sunucuları Hakkında Genel Bilgi

Pekala, bir e-posta sunucusu birçok standardı bünyesinde barındırır. Gelen postalar için IMAP(Internet Message Access Protocol), POP3(Post Office Protocol 3) gibi protokoller söz konusuyken, giden posta tarafında SMTP(Simple Mail Transfer Protocol) devreye girer. En başından beri bu protokollerin baz aldığı 25, 465, 587, 2525, 110, 143, 993 vb. portlar da söz konusudur.

Bu çalışmadaki amacım gerçek anlamda kullanılabilir ve üretim(production) ortamına konabilecek bir e-posta sunucusu yazmak değil elbette. Entegrasyon testleri sırasında SMTP protokolünün temel bazı komutlarını HELO/EHLO, MAIL FROM, RCPT TO, DATA, QUIT taklit eden, gelen mesajları diske yazan ve gerektiğinde belirli senaryolarda hata da dönebilen hafif sıklet(lightweight) bir sahte(fake) sunucu işimi görüyor.(Hata dönmesi sunucudan istenen cevap alınamadığında sistemin kalan kısmının nasıl davranış göstereceğini anlamak açısından da önemli olabilir) Böylece test ortamında gerçek bir SMTP sağlayıcısına bağımlı kalmadan, e-posta gönderim akışının uçtan uca doğru çalıştığını doğrulayabiliyordum.

Tabii ki tam teşekküllü bir SMTP sunucusu yazmayı da düşünebiliriz. Bu durumda protokolün rfc5321 standardına uygun olarak tüm komutları ve hata durumlarını ele almamız gerekecektir. Bakınız RFC 5321. Bizim demomuzda çok basit birkaç komutu ele alıyoruz.

Gerekli Küfelerin Yüklenmesi

Rust projesini(executable) oluşturduktan sonra gerekli crate eklemelerini yaparak işe başlayalım. Örnek kodları yazdığım tarih itibariyle(2025 ortaları gibi) toml içeriği aşağıdaki gibiydi. Paket sürümlerinde güncellemeler olduğunu söyleyebilirim. Buna göre son sürümleri ile de çalışabilirsiniz.

[package]
name = "light_mail_server"
version = "0.1.0"
edition = "2021"

[dependencies]
env_logger = "0.11.6"
log = "0.4.25"
tokio = { version = "1.43.0", features = ["full"] }

En önemli modülümüz asenkron kabiliyetleri ile öne çıkan tokio küfesi(crate). Bunun haricinde sunucu tarafı için log bırakmak da iyi olacaktır; nitekim uygulamayı bir Docker container'ı olarak ayağa kaldırdığımızda terminal loglarından durumu inceleme şansımız da olur. log ve env_logger küfelerini bu amaçla kullanıyoruz. Bu küfeleri doğrudan toml dosyasına yazabileceğiniz gibi aşağıdaki terminal komutları ile de ekleyebiliriz.

cargo add env_logger, log
cargo add tokio -F full

İhtiyacımız Olan Bazı Sabitler ve Utility

SMTP protokolünü bir nebze taklit edeceğimiz için olaya dahil olan komutları ve sunucunun vereceği cevapları bir enum türünde toplamayı tercih ettim. OCaml genlerinden gelen zengin bir enum türü var, her fırsatta söylemek istiyorum.

use std::fmt::{Display, Formatter};

pub enum Command {
    Hello,
    Hello2,
    HelloResponse,
    From,
    To,
    Data,
    Bye,
    Ok,
    Quit,
    Unrecognized,
    EndDataReply,
    ServiceNotAvailable,
    ServerReady,
    MessageAccepted,
    ErrorSimulated,
}

impl Command {
    pub fn as_str(&self) -> &'static str {
        match self {
            Command::Hello => "HELO",
            Command::Hello2 => "EHLO",
            Command::HelloResponse => "250 Hello\r\n",
            Command::From => "MAIL FROM",
            Command::To => "RCPT TO",
            Command::Data => "DATA",
            Command::Bye => "221 Bye\r\n",
            Command::Ok => "250 OK\r\n",
            Command::Quit => "QUIT",
            Command::Unrecognized => "500 Unrecognized command\r\n",
            Command::EndDataReply => "354 End data with <CR><LF>.<CR><LF>\r\n",
            Command::ServiceNotAvailable => "421 Service Not Available\r\n",
            Command::ServerReady => "220 Mock SMTP Server Ready\r\n",
            Command::MessageAccepted => "250 Message accepted for delivery\r\n",
            Command::ErrorSimulated => "421 Error simulated for recipient.",
        }
    }
}

impl Display for Command {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.as_str())
    }
}

pub const BUFFER_SIZE: usize = 1024;
pub const EMAIL_DIR: &str = "temp";
pub const INVALID_MAIL: &str = "thereisnomail@nowhere.nowhere";
pub const ENDS_WITH: &str = "\r\n.\r\n";
pub const NO_BUFF_OR_EOF:usize = 0;

Command enum yapısı hem istemciden gelmesini beklediğimiz komutları(HELO/EHLO, MAIL FROM, RCPT TO, DATA, QUIT) hem de sunucunun geri döneceği cevapları(220, 250, 354, 421, 500 gibi klasik SMTP durum kodlarını) aynı tip altında topluyor. as_str() her varyanta karşılık gelen ham metni döndürüyor, Display trait'i de bu string'i {} ile doğrudan formatlayabilmemizi sağlıyor. Böylece sunucu tarafında "hangi duruma hangi metni yazacağız" sorusunu enum üzerinden, tip güvenli(type safe) bir şekilde çözmüş oluyoruz. Kodun kalan kısmında yer alan sabitlerin kullanım amaçları ise aşağıdaki gibi.

BUFFER_SIZE soket okumalarında kullanılacak tampon boyutu.
EMAIL_DIR gelen e-postaların diske yazılacağı klasör.
ENDS_WITH ise SMTP protokolünde DATA komutunun bitişini işaret eden \r\n.\r\n dizisini temsil ediyor.
INVALID_MAIL, testlerde bilerek hataya düşürmek istediğimiz senaryolar için ayırdığımız özel bir alıcı adresi. Sunucu bu adresi gördüğünde normal akışı bozup 421 hatasını simüle ediyor.
NO_BUFF_OR_EOF değeri socket.read'in 0 döndüğü(yani karşı tarafın bağlantıyı kapattığı) durumu isimlendirerek kodun okunabilirliğini artırıyor.

İhtiyaç duyabileceğimiz çok basit iki fonksiyonu ise utility.rs isimli dosyada tutmayı tercih ettim.

use crate::constants::*;
use log::*;
use std::fs::OpenOptions;
use std::io::Write;
use std::time::{SystemTime, UNIX_EPOCH};
use tokio::io::AsyncWriteExt;
use tokio::net::TcpStream;

pub fn save_email(body: &str) -> std::io::Result<()> {
    let timestamp = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs();
    let filename = format!("{}/email_{}.txt", EMAIL_DIR, timestamp);

    let mut file = OpenOptions::new()
        .create(true)
        .truncate(true)
        .write(true)
        .append(false)
        .open(&filename)?;

    file.write_all(body.as_bytes())?;
    info!("Email saved to {}", filename);

    Ok(())
}

pub async fn send_response(socket: &mut TcpStream, command: Command) -> tokio::io::Result<()> {
    socket
        .write_all(command.as_str().as_bytes())
        .await
        .map_err(|e| {
            error!("Failed to send response '{}': {}", command.as_str(), e);
            e
        })
}

save_email fonksiyonu, DATA bloğunda toplanan e-posta içeriğini alıp temp/email_<unix_timestamp>.txt formasyonunda isimlendirerek metin tabanlı bir dosyaya kaydediyor. Böylece testler sırasında gerçekten ne gönderilmiş sorusunun cevabını sunucuya hiç dokunmadan diskten okuyabiliriz(Tabii diske yazma yetkisine sahip olunması gerekir) send_response fonksiyonu ise asenkron tarafta tekrar tekrar ele alacağımız "soket'e bir Command cevabı yaz" işlemini tek bir yerden kontrol etmek için kullanılıyor. Hata durumunda ise log üzerinden bir error! satırı bırakıp hatayı çağırana geri döndürüyor. Bu iki fonksiyonu kullandığımız yerleri görünce kafanızda daha net canlanacaktır diye düşünüyorum.

Sunucu Tarafı

Sunucu görevini Server isimli bir struct karşılıyor. Tabii bu metodun bir TcpStream üzerinde çalışması ve geriye tokio çalışma zamanının kullanabileceği bir Result nesnesi döndürmesi gerekiyor.

use crate::constants::*;
use crate::utility::*;
use log::*;
use std::io::ErrorKind;
use tokio::io::AsyncReadExt;
use tokio::net::TcpStream;

pub struct Server {}

impl Server {
    pub async fn handle(socket: &mut TcpStream) -> tokio::io::Result<()> {
        send_response(socket, Command::ServerReady).await?;

        let mut buffer = [0; BUFFER_SIZE];
        let mut email_body = String::new();
        let mut data_mode = false;

        loop {
            match socket.read(&mut buffer).await {
                Ok(NO_BUFF_OR_EOF) => {
                    info!("Connection closed by client");
                    break;
                }
                Ok(n) => {
                    let request = String::from_utf8_lossy(&buffer[..n]);
                    info!("Received: {}", request);

                    if data_mode {
                        email_body.push_str(&request);

                        if email_body.ends_with(ENDS_WITH) {
                            let clean_body = email_body.trim_end_matches(ENDS_WITH);
                            if let Err(e) = save_email(clean_body) {
                                error!("Failed to save email: {}", e);
                            }
                            email_body.clear();

                            send_response(socket, Command::MessageAccepted).await?;
                            data_mode = false;
                        }
                    } else {
                        match request.trim() {
                            r if r.starts_with(Command::Hello.as_str())
                                || r.starts_with(Command::Hello2.as_str()) =>
                            {
                                send_response(socket, Command::HelloResponse).await?;
                            }
                            r if r.starts_with(Command::From.as_str()) => {
                                send_response(socket, Command::Ok).await?;
                            }
                            r if r.starts_with(Command::To.as_str()) => {
                                if r.contains(INVALID_MAIL) {
                                    send_response(socket, Command::ServiceNotAvailable).await?;
                                    error!("{}", Command::ErrorSimulated.as_str());
                                } else {
                                    send_response(socket, Command::Ok).await?;
                                }
                            }
                            r if r.starts_with(Command::Data.as_str()) => {
                                send_response(socket, Command::EndDataReply).await?;
                                data_mode = true;
                            }
                            r if r.starts_with(Command::Quit.as_str()) => {
                                send_response(socket, Command::Bye).await?;
                                info!("Session closed");
                                break;
                            }
                            _ => {
                                send_response(socket, Command::Unrecognized).await?;
                                error!("Unrecognized command received: {}", request);
                            }
                        }
                    }
                }
                Err(e) if e.kind() == ErrorKind::ConnectionReset => {
                    warn!("Connection reset by peer");
                    break;
                }
                Err(e) => {
                    error!("Error reading from socket: {}", e);
                    break;
                }
            }
        }

        Ok(())
    }
}

Server::handle fonksiyonunu tek bir TCP bağlantısının tüm yaşam ömrünü yöneten bir metot olarak düşünebiliriz. Bağlantı geldiği anda önce 220 Mock SMTP Server Ready cevabıyla kendini tanıtıyor(tıpkı gerçek bir SMTP sunucusunun yaptığı gibi), sonra sonsuz bir döngüde soketten veri okumaya devam ediyor. Burada iki mod arasında gidip geliyoruz. data_mode false iken gelen her satırı bilinen SMTP komutlarıyla(HELO/EHLO, MAIL FROM, RCPT TO, DATA, QUIT) eşleştirip uygun cevabı dönüyoruz. DATA komutu geldiğinde ise data_mode değerini true yapıp asıl e-posta gövdesini(body) toplamaya başlıyoruz. Gövde, protokolün bitiş işareti olan \r\n.\r\n dizisiyle karşılaşana kadar email_body içinde biriktiriliyor, karşılaşınca da save_email ile diske yazılıp 250 Message accepted for delivery cevabı dönülüyor.

RCPT TO adımında ayrıca küçük bir "hata simülasyonumuz" var. Talep, constants.rs'te tanımladığımız INVALID_MAIL adresini içeriyorsa sunucu bilerek 421 Service Not Available dönüyor. Bu, istemci tarafındaki hata yönetimi kodunu(örneğin bir SmtpException yakalama bloğunu) gerçek bir sunucuya ihtiyaç duymadan test edebilmemi sağlıyor. Bağlantı QUIT ile ya da karşı tarafın soketi kapatmasıyla(okuma 0 bayt dönünce) sonlanıyor. ConnectionReset gibi beklenmedik durumlar oluştuğundaysa loga bilgi düşürülüp döngüden çıkılıyor.

Her şeyi main fonksiyonunda topluyoruz. Tokio çalışma zamanını kullandığımız için metodumuz hem asenkron hem de [tokio::main] direktifi ile işaretlenmiş durumda.

use crate::constants::*;
use crate::server::Server;
use log::*;
use std::env;
use tokio::fs::create_dir_all;
use tokio::net::TcpListener;

mod constants;
mod server;
mod utility;

#[tokio::main]
async fn main() -> tokio::io::Result<()> {
    env::set_var("RUST_LOG", "tokio=info,light_mail_server=info");
    env_logger::init();

    create_dir_all(EMAIL_DIR).await?;

    let listener = TcpListener::bind(("0.0.0.0", 2525)).await?;
    info!("Light SMTP Server running on 0.0.0.0:2525");

    loop {
        let (mut socket, addr) = listener.accept().await?;
        info!("Connection received from {}", addr);

        tokio::spawn(async move {
            Server::handle(&mut socket)
                .await
                .expect("Failed to run server");
        });
    }
}

Uygulamanın giriş noktası olan main.rs fonksiyonu klasik bir tokio giriş noktası. Önce RUST_LOG ortam değişkenini ayarlayıp env_logger ortamını başlatıyoruz, ardından e-postaların yazılacağı EMAIL_DIR klasörünün var olduğundan emin oluyoruz(create_dir_all klasörü zaten varsa hata vermiyor). Sonrasında 0.0.0.0:2525 üzerinde bir TcpListener açılıyor(yani sunucu tüm ağ arayüzlerinden 2525 portuna gelen bağlantıları dinlemeye başlıyor). Sonsuz döngüde her yeni bağlantı kabul edildiğinde tokio::spawn ile ayrı bir asenkron görev(task) başlatılıyor ve o bağlantının tüm yaşam döngüsü Server::handle metoduna devrediliyor. Böylece birden fazla istemci aynı anda bağlanabiliyor ve her biri kendi görevinde, birbirinden bağımsız şekilde ele alınabiliyor.

İlk Testler

Dilerseniz uygulamayı bu noktada çalıştırıp en azından ayağa kalkıp kalkmadığına bakalım.

Dockerize İşlemleri

Örneğimiz hazır ve işler durumda görünüyor. Bu çalışmayı yaptığımda örneği bir Docker Container olarak ayağa kaldırıp kullanmıştım. Dockerize işlemleri için bir imaj(image) oluşturmamız gerekiyor. Bunun için uygulamanın çalışacağı ortamı ve gereksinimleri tanımlayan bir Dockerfile dosyasına ihtiyacımız var. Onu da aşağıdaki gibi yazabiliriz.

FROM rust:1.84.0 AS builder

WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y libssl-dev ca-certificates && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=builder /app/target/release/light_mail_server /app/

CMD ["./light_mail_server"]

Dockerfile, iki aşamalı(multi-stage) bir yapı kullanıyor. İlk aşamada rust:1.84.0 imajı üzerinde cargo build --release ile derleme yapılıyor. İkinci aşamada ise sadece derlenmiş binary, çok daha küçük olan debian:bookworm-slim imajına kopyalanıyor. Bu sayede son imaj, Rust derleyicisini ve ara derleme dosyalarını içermiyor. Sadece çalıştırılabilir dosyayı ve gerekli sertifikaları barındırıyor. Bir nevi imajı optimize edip çalışma zamanı maliyetini düşürmüş oluyoruz diyebilirim. İmajı oluşturmak ve tek başına çalıştırmak için aşağıdaki komutları kullanabiliriz.

# Docker imajını oluşturmak için
docker build -t light-mail-server .

# İmajı doğrudan çalıştırmak için
docker run -p 2525:2525 light-mail-server

Buna bağlı olarak işi kolaylaştırmak adına bir docker-file dosyası içerisine servis tanımını da ekleyebiliriz.

services:
  light-mail-server:
    build: .
    ports:
      - "2525:2525"

O Zaman Bir İstemci(Client) Yazalım

Artık ortamımızda Docker container olarak çalışan ve temel SMTP hizmetini taklit eden bir e-posta sunucumuz var. Peki nasıl kullanacağız? İstemci tarafını .NET tabanlı basit bir konsol uygulaması olarak tasarlayabiliriz. Aşağıdaki kod örneği gayet yeterli olacaktır.

using System.Net.Mail;

SendEmail("burak.selim@azon.com", "<h1>Challenge Accepted</h1><p>This is a sample e-mail from dotnet client</p>", true);
SendEmail("thereisnomail@nowhere.nowhere", "<h1>Error Test</h1><p>We are waiting for 421 error.</p>", true);

static void SendEmail(string to, string body, bool isHtml)
{
    try
    {
        var client = new SmtpClient("127.0.0.1", 2525)
        {
            DeliveryMethod = SmtpDeliveryMethod.Network
        };

        var message = new MailMessage("test.pilot@azon.com", to, "Demonstration Subject", body)
        {
            IsBodyHtml = isHtml
        };

        Console.WriteLine($"Sending email to {to}...");
        client.Send(message);
        Console.WriteLine("Email sent successfully!\n");
    }
    catch (SmtpException ex)
    {
        Console.WriteLine($"SMTP Error: {ex.StatusCode} - {ex.Message}\n");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"General Error: {ex.Message}\n");
    }
}

İstemci taraf, System.Net.Mail.SmtpClient sınıfını kullanıyor ve 127.0.0.1:2525 adresine, yani bizim light_mail_server'ımıza bağlanacak şekilde ayarlanıyor. SendEmail fonksiyonu bilerek iki farklı senaryoyu deniyor. İlk çağrıda normal bir HTML e-postası gönderiliyor ve sunucu bunu 250 Message accepted for delivery ile onaylıyor. İkinci çağrıda ise alıcı olarak sunucu tarafında özel anlam taşıyan thereisnomail@nowhere.nowhere adresi veriliyor. Bu adres, RCPT TO aşamasında sunucuyu bilerek 421 Service Not Available dönmeye zorluyor ve istemci tarafındaki catch(SmtpException ex) bloğunun(yani test etmek isteyeceğimiz hata yönetimi kodunun) gerçekten çalıştığını, hakiki bir SMTP sağlayıcısına ihtiyaç duymadan doğrulamış oluyoruz.

Öyleyse taze taze bir deneme yapalım. Önce docker container'ı başlatalım ve istemci uygulamayı çalıştıralım. Ben Windows sistemimde aşağıdaki ekran görüntüsünde yer alan sonuçlara ulaştım.

O zamanlar benim için keyifli bir çalışma olmuştu. Yaklaşık bir sene sonrasında şöyle bir geriye dönüp bakınca yazı haline getirmenin iyi olacağına karar verdim. Umarım sizler için de faydalı bir pratik olur. Böylece geldik bir maceramızın daha sonuna. Tekrardan görüşünceye dek hepinize mutlu günler dilerim.

Github reposunda rust program kodlarına ulaşabilirsiniz.

Kendi Bevy'ni Yazmaya Çalışmak: C# ile Basit Bir ECS Denemesi

2026-09-02T07:59:00+00:00

Bir süre Rust programlama dili ile oyun geliştirmeye çalışmıştım. Topluluğun gücü olsa gerek Are We Game Yet sitesinde birçok framework, oyun motoru, render platformu vs var. En çok kullanılan platformlardan birisi sanıyorum ki Bevy. Onu özel kılan yönlerden birisi Composition over Inheritance prensibini merkeze alan Entity Component System implementasyonu da sunması. Bir önceki cümlede iki önemli kavramdan bahsettim; kalıtım yerine kompozisyonun tercih edilmesi ve entity nesneleri ile donatılmış bileşenlerin ele alındığı sistemler yaklaşımı. Bu yazıdaki amacım Rust tarafında ECS kullanımını göstermekten ziyade söz konusu yaklaşımı C# gibi nesne yönelimli bir dilde tasarlamak istersek nasıl bir yol izleyebileceğimizi keşfetmek(Bevy ile ilgili bir denememi merak ediyorsanız On My Way isimli oyunuma bakabilirsiniz)

Oyundan muhteşem bir enstantane :P

Rust Tarafında Nasıldı?

Bevy'nin o zamanlar kullandığım sürümünü baz alarak On My Way oyunundaki main fonksiyonunu kısaca değerlendirelim.

mod events;
mod game;
mod main_menu;
mod systems;

use crate::events::GameOverEvent;
use crate::game::GamePlugin;
use crate::main_menu::MainMenuPlugin;
use crate::systems::*;
use bevy::prelude::*;

fn main() {
    App::new()
        .add_message::<GameOverEvent>()
        .add_plugins(DefaultPlugins)
        .init_state::<AppState>()
        .add_plugins((GamePlugin, MainMenuPlugin))
        .add_systems(Startup, spawn_camera)
        .add_systems(
            Update,
            (
                change_to_game_state,
                change_to_main_menu,
                handle_game_over,
                exit_game,
            ),
        )
        .run();
}

#[derive(States, Debug, Clone, Eq, PartialEq, Hash, Default)]
pub enum AppState {
    #[default]
    MainMenu,
    Game,
    GameOver,
}

Oyun döngüsü aslında bir durum makinesi(State Machine) gibi düşünülebilir. Bu state'ler menüde olma, oyunu oynama ve oyunda yanma hallerini ele alıyor. Bevy sağladığı zincir fonksiyonelliklerle bu makine için gerekli tüm unsurları sağlıyor. Örneğin ekranla ilgili bilgiler veya kamera özellikleri dahili olarak sağladığı plug-in'ler üzerinden geliyor. Kendi tasarladığımız plug-in'ler de ise oyundaki varlıkları(entities), bileşenleri(components) ve işleyen sistemleri tarifleyebiliyoruz. Tüm bunlar durum makinesinin işletildiği sonsuz döngüde güncellemeler sırasında(Frame per second anlarında) veya başlangıç durumunda devreye giriyor. Burası kodun son derece yalınlaştığı bir sorumluluklar zinciri(Chane of responsibility) implementasyonu. Konuyu biraz daha açmak adına örnek bir plug-in kurgusunu masaya yatıralım. Oyuncunun kullandığı uzay gemisini ele alarak başlayalıım. Bu veri yapısı aslında sistem içerisinde bir varlıkla ilişkilendirilecek bir bileşen(component).

use bevy::prelude::*;
#[derive(Component)]
pub struct Spaceship {}

Onun bir bileşen olduğunu Component direktifi ile Bevy oyun motoruna bildiriyoruz. Aslında bu veri yapısı çoğunlukla tek başına değil oyun motoru tarafında üretilen bir varlıkla(entity) ilişkilendirilerek kullanılıyor. Pek tabii bu tip bir veri modeli çeşitli özelliklere de sahip olabilir. Örneğin aşağıdaki roket veri yapısını göz önüne alalım.

use bevy::prelude::*;
#[derive(Component, Clone)]
pub struct Missile {
    pub direction: Vec2,
    pub speed: f32,
    pub width: f32,
    pub fuel_cost: f32,
    pub disposable: bool,
    pub location: Vec3,
}

Bir roketin yönü, hızı, yakıt miktarı, konumu gibi bilgiler de lazım olur. Zira oyuncu bir tuşa basıp füzeyi fırlattığında aslında yeni ve benzersiz bir entity oluştururken başka bir sistemde bu entity'nin değerlerini ele alarak çeşitli güncellemeler yapar. Füze, belirtilen yöne doğru belli bir hızda ama yakıtı tükenene kadar hareket eder. Tüm bu değerlendirmeler oyun motorunun sonsuz döngüsündeki anlık güncellemelerde değerlendirilir. System olarak ifade edilen fonksiyonlarsa bu güncellemeleri üstlenerek varlıkların verilerinde ya da uygulama durumlarında değişiklikler yaparlar. Örneğin bir füzenin hareketi sadece buna odaklanmış bir sistemle ele alınabilir. Aşağıdaki fonksiyon tam olarak bu görevi üstleniyor.

pub fn move_missile(mut query: Query<(&mut Transform, &Missile)>, time: Res<Time>) {
    for (mut transform, missile) in query.iter_mut() {
        let direction = Vec3::new(missile.direction.x, missile.direction.y, 0.);
        transform.translation += direction * missile.speed * time.delta_secs();
    }
}

Bu fonksiyonun parametre yapısı son derece önemli. Query generic bir tür ve aslında sahada değiştirilebilir Transform özelliği olan Missile referanslarını bekliyor. Sahada füzelerin olması oyuncunun tuşa basmasına bağlı ancak bu sistem tuşa basılma halini değil ortamda hareket halinde olması beklenen füze varlıklarına ait referanslar var mı sorusunu cevaplıyor. Hatta sistemler arasındaki zamansal kaymaların önüne geçmek için delta farklarını da bir Resource üzerinden ele alıyor. Şimdi kafayı biraz karıştıralım. Oyuncu tuşa basıp füze ateşleyecek. Aslında bu da bir sistem olarak ele alınmalı. Aşağıdaki fonksiyon bu işi üstleniyor.

pub fn fire_missile(
    mut commands: Commands,
    mut query: Query<&mut Transform, With<Spaceship>>,
    keyboard_input: Res<ButtonInput<KeyCode>>,
    asset_server: Res<AssetServer>,
    launch_timer: Res<MissileLaunchCheckTimer>,
    mut live_data: ResMut<LiveData>,
) {
    if keyboard_input.pressed(KeyCode::KeyS) && launch_timer.timer.just_finished() {
        if let Ok(transform) = query.single_mut() {
            let missile = Missile {
                direction: Vec2::new(1., 0.),
                speed: MISSILE_003_SPEED,
                width: 51.,
                fuel_cost: 1.5,
                disposable: false,
                location: transform.translation,
            };
            commands.spawn((
                Sprite {
                    image: asset_server.load("sprites/spaceMissiles_003.png"),
                    ..default()
                },
                Transform::from_xyz(
                    transform.translation.x,
                    transform.translation.y,
                    0.,
                ),
                missile.clone(),
            ));
            live_data.spaceship_fuel_level -= missile.fuel_cost;
            live_data.used_missile_count += 1;
        }
    }
}

Kodun ilk etapta korkutucu geldiğini ifade edebilirim. Bu yazı açısından değerlendirirsek önemli olan noktaları vurgulamamız yeterli olacaktır. Sistemin ihtiyaç duyacağı birçok malzeme parametre üzerinden geliyor. Tuşa basılma durumunu kontrol edebileceğimiz, füze resmini gösterebileceğimiz, füze için sayaç başlatabileceğimiz bazı kavramlar oyun için birer kaynak(Resource). Bir entity oluşturmamız gerektiğinden Commands bileşeni aktarılıyor. Elbette füzeyi ateşlemesi için ortamda birde Spaceship olması lazım. Ancak bu sistem fonksiyonu için değiştirilebilir Transform bileşeni ile donatılmış bir Spaceship varlığına ihtiyaç var, işte bunu da Query karşılıyor. Anlayacağınız çalışma zamanında sistemler üzerinde çalışacakları varlıkları onları donattığımız bileşenler yardımıyla keşfedip kullanabilmekte ve ihtiyaç duydukları kaynakları(resim, ses, zamanlayıcı vs) yine genel ortamdan isteyebilmekte.

Eğer kodları detaylıca incelerseniz sayısız sistem ve bileşen olduğunu göreceksiniz. Bunları yönetmek klasik bir kodlama ile çok kolay değil. ECS(Entity Component System) gibi prensiplerin uyarlanması oyun motorlarında bazı işleri oldukça kolaylaştırıyor.

Pekala, elimizde entity haline dönüşen veri yapıları, onları çeşitli karakteristiklerle donatabildiğimi bileşenler ve işlediğimiz sistemler var. Bunların sayısı bir noktadan sonra yönetilmesi zor bir hale gelebiliyor. Aynı kapsama(context) dahil olacak her şeyi paketlemek ve bir eklenti haline getirmek mümkün(Bundle plug-in) Örneğin füzelerin kapsamını göz önüne alırsak şöyle bir plug-in kullanabiliyoruz.

use crate::game::missile::systems::*;
use crate::AppState;
use bevy::prelude::*;

pub mod components;
mod systems;
pub struct MissilePlugin;

impl Plugin for MissilePlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(
            Update,
            (
                move_missile,
                detect_collision_with_meteors,
                claim_hitted,
                check_outside_of_the_bounds,
                animate_explosion_sprites,
                despawn_explosions,
            )
                .run_if(in_state(AppState::Game)),
        )
        .add_systems(OnExit(AppState::Game), despawn_missiles);
    }
}

Bevy bunun bir plugin olduğunu implement ettiği Plugin trait dolayısıyla biliyor. Bu trait parametre olarak uygulama nesnesini kullanıyor ve böylece çalışma zamanına sistem ekleme kabiliyeti kazanılıyor. İşte ilk başta gösterdiğimiz main fonksiyonu içerisindeki plug-in bildirimleri aslında kendi kapsamlarından birçok enstrümanı çalışma zamanı enjekte edebiliyor.

ECS Hangi Avantajları Getiriyor?

İlk başta alışmakta zorlandığım bir programlama paradigmasıydı. Özellikle Bevy oyun motorunun da sürekli değişmesi ve tam bir stabil sürüme gelmemesi işimi zorlaştırmıştı. Ancak önemli olan ECS'in getirdiği avantajları da anlamak. Bunları birkaç başlık altında toplayabiliriz.

Kompozisyonun kalıtıma tercih edilmesi(Composition over Inheritance): Klasik nesne yönelimli bir oyun motorunda genelde GameObject temelli, derin bir kalıtım ağacı kurma eğiliminde oluruz. Meteor, Spaceship, Missile gibi tipler ortak bir taban sınıftan türer, hareket edebilme, çizilebilme, hasar alabilme gibi yetenekler bu ağacın farklı katmanlarına dağılır. Zamanla elmas problemi(diamond problem) olarak da bilinen, bir sınıfın hem hareket edebilen hem menzili olan hem de çizilebilen bir şey olması gerektiğinde kalıtım ağacının nereye oturacağının belirsizleştiği açmaza düşebiliriz. ECS'de böyle bir kaygı yoktur. Nitekim bir varlık hangi davranışlara ihtiyaç duyuyorsa o kadar bileşenle donatılır, hatta çalışma zamanında bile bir bileşen eklenip çıkarılarak ilgili varlığın davranışı değiştirilebilir. Söz gelimi bizim örneğimizdeki tower sadece Position ve Range bileşenlerini taşırken player hem Position hem Velocity bileşenleri ile donatılmıştır. Aralarında hiçbir kalıtım ilişkisi kurmamıza gerek kalmamıştır.
Veri(data) ile davranışın(behavior) birbirinden ayrılması: Bileşenler saf veri, sistemler ise bu veri üzerinde çalışan fonksiyonlar olarak düşünülebilir. Bu ayrım test edilebilirliği artırır. Bu sayede bir sistemi test etmek için koca bir oyun dünyası kurmaya gerek de kalmaz. Duruma uygun birkaç bileşen örneği hazırlayıp Apply metodunu çağırmak yeterli olacaktır. Aynı zamanda "bu davranış hangi sınıfa ait olmalı" tartışması da ortadan kalkar. Davranış(behavior) artık bir sınıfa değil, o davranışı üstlenen sisteme ait hale gelir.
Performans: Gerçek ECS motorları bileşenleri bellekte birbirine yakın kompakt dizilerde tutmakta(Structure of Arrays yaklaşımı) Bir sistem sadece ilgilendiği bileşen tipini taradığında CPU cache dostu bir erişim deseni ortaya çıkar. Bizim C# denememizde bunu henüz sağlamayacağız(Bir süre sonra...Sağlayamadı), List<IComponent> içinde OfType<T>() ile filtreleme yapıyoruz ki bu hem tip kontrolü hem de LINQ işlem maliyeti taşıyor ama gerçek bir ECS motorunun neden bu kadar performans vaadinde bulunduğunu anlamak için bu noktayı bilmekte fayda var.
Paralellik: Sistemler hangi bileşenlere okuma/yazma erişimi istediklerini query üzerinden bildirdiklerinde, birbiriyle çakışmayan sistemler aynı anda farklı thread'lerde çalıştırılabilir. Bevy'nin zamanlayıcısı(scheduler) bunu otomatik olarak çözer. Örneğin move_missile ile hiçbir ortak bileşeni olmayan başka bir sistemi aynı frame içinde paralel koşturabilir. Bizim tasarlayacağımız Scheduler sınıfı şu an için tamamen sıralı düzende çalışıyor ama mimarinin ileride bu tür bir genişlemeye kapalı olmadığını açıkça belirtmek isterim.

Gelelim C# Tarafına

Bevy'nin sağladığı ECS yetkinlikleri oldukça önemli seviyede. Peki C# gibi bir nesne yönelimli dili göz önüne alırsak bu tip bir geliştirmeyi nasıl yaparız? En azından bir entity ve component ikilisi bir sistemde yürütebilmek ama bunu çalışma zamanındaki ana motor üstünden sağlayabilmek ilk amaç olabilir. Yazının devam eden kısmında işte bu maceraya dalıyor olacağız. İşe temiz bir Console uygulaması ile başlamakta yarar var. Engine olarak isimlendirdiğim dosya içeriğini aşağıdaki gibi doldurdum.

namespace NetBevy;

public interface IComponent
{
}

public interface IEntity
{
    Guid ID { get; set; }
    List<IComponent> Components { get; set; }
    void AddComponent(IComponent component);
}

public class Entity
    : IEntity
{
    public Guid ID { get; set; }
    public List<IComponent> Components { get; set; } = [];

    public void AddComponent(IComponent component)
    {
        Components.Add(component);
    }
}

public interface ISystem<T> where T : IComponent
{
    void Apply(IEnumerable<(Entity entity, T component)> components);
}

public enum SystemState
{
    Startup,
    Update
}

public class Scheduler
{
    private readonly World _world;

    private Dictionary<SystemState, List<object>> _systems = new()
    {
        { SystemState.Startup, new List<object>() },
        { SystemState.Update, new List<object>() }
    };

    public Scheduler(World world) => _world = world;

    public void AddSystem<T>(SystemState state, ISystem<T> system) where T : IComponent
    {
        _systems[state].Add(system);
    }

    public void Run(SystemState state)
    {
        if (!_systems.TryGetValue(state, out List<object>? value)) return;

        foreach (var system in value)
        {
            var systemType = system
                .GetType()
                .GetInterfaces()
                .FirstOrDefault(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(ISystem<>));

            if (systemType != null)
            {
                var componentType = systemType.GetGenericArguments()[0];
                var queryType = typeof(Query<>).MakeGenericType(componentType);
                var queryInstance = Activator.CreateInstance(queryType, _world);
                var getEntitiesMethod = queryType.GetMethod("GetEntities");
                var entities = getEntitiesMethod.Invoke(queryInstance, null);

                var applyMethod = systemType.GetMethod("Apply");
                _ = applyMethod.Invoke(system, [entities]);
            }
        }
    }
}


public class World
{
    private List<Entity> _entities = [];

    public Entity CreateEntity()
    {
        var entity = new Entity { ID = Guid.NewGuid() };
        _entities.Add(entity);
        return entity;
    }

    public IEnumerable<Entity> GetEntities() => _entities;
}

public class Query<T> where T : IComponent
{
    private readonly World _world;

    public Query(World world) => _world = world;

    public IEnumerable<(Entity entity, T component)> GetEntities()
    {
        return _world.GetEntities()
            .SelectMany(e => e.Components
                .OfType<T>()
                .Select(c => (e, c)));
    }
}

Şimdi burada neler olduğuna birlikte bakalım. Ne yapmak istediğimize dikkat etmemiz lazım. Engine içerisindeki enstrümanlar asıl oyun programcısının ekleyeceği ve motorun hiçbir suretle bilemeyeceği ama ele alması gereken kavramları sağlamalı. Bu nedenle arayüzler(interface) bizim için önemli aktörlerden birisi. Bileşenleri tariflemek için IComponent arayüzünü kullanıyoruz. Şu an için bir bileşenin oyun programıcısı tarafından mutlaka ele alması gereken davranışları(behavior) yok.

Entity'ler aslında programcının motordan istediği ve üretilen(spawn) şeyler. Benzersiz bir kimlikleri olması ve ayrıca bileşenler ile donatılabilmeleri gerekiyor. Bir varlığın bileşenlerle donatılması aslında bize şöyle bir imkan sağlıyor; oyun başlar ve karakter sahaya gelir(spawn) ve gelirken zırhlanır, ateş gücü kazanır, hareket eder vs. Zırhlanabilir, ateş edebilir(Weapon), hareket edebilir(Moveable) aslında programcının tanımladığı ve belli nitelikler taşıyan bileşenler olarak düşünülebilir. O halde sistemin bir varlığın nasıl tanımlanıp neler yapabileceğinin de tariflenmesi gerekiyor. Bu nedenle IEntity arayüzü içerisinde Guid türünden bir özellik(düşündüm de şimdi sadece readonly de yapılabilirmiş), bileşen eklemeyi sağlayan bir metot(AddComponent) ve sahip olduğu bileşenleri çekmemizi sağlayan başka bir özellik yer alıyor.

Varlıkların ve bileşenlerin oyun motoru için gerekli olan sözleşmeleri(contracts) hazır. Bunların değerlendirileceği yer ise sistemler. Ve sistemler yine oyun programcısı tarafından tanımlanıyor. Oyun motoru oyunun kullandığı sistemler hakkında bilgi sahibi olamaz ama hangi kurallara uymaları gerektiğini sözleşemeler aracılığıyla belirtebilir. Bunu ISystem arayüzü ile sağlıyoruz. Dikkat edileceği üzere sistem sözleşmesi generic ve T türünün IComponent implementasyonu yapmış olmasını bekliyor. Tek bir davranışı var o da Apply. Metodun parametre yapısı üzerinden hareket edersek Entity ve IComponent tuple'larından oluşan numaralanabilir bir liste aldığını görebiliriz. Tabii bu çok ilkel bir sistem fonksiyonelliği. Rust gibi motorların sağladığı varyasyonlar düşünüldüğünde inanılmaz derecede yalın kalıyor. Ancak hedefe giden yolda işimize yarayacağını açıkça söyleyebilirim.

Bevy tarafındaki sistem fonksiyonlarını hatırlarsanız eğer dünyaya hükmetmek için Command ve dünyadaki şeyleri çetrefilli biçimde sorgulayabilmek için akıllı bir Query bileşenine sahipti. Burada benzer bir işlevselliği sağlamak için program kodun alt kısımlarında göreceğiniz World ve generic Query sınıflarını kullanıyoruz. World sınıfı aslında oyun motorunun sağladığı dünyadaki enstrümanları sunuyor diyebiliriz. Şu an için sadece Entity'leri yönetiyoruz. Entity oluşturmak ve hafızaya almak var olan entity listesini çekmek sağladığı fonksiyonellikler. Generic Query sınıfı ise bir World nesne örneği ile var olabilen bir bileşen. Sınıfın belki de en önemli noktası GetEntities içerisindeki LINQ(Language INtegrated Query) sorgusu. Entity'leri alırken söz konusu bileşene sahip olanları çekiyor. Tabii şu an için tek seviyede bir sorgulama mümkün. Örneğin, hareket edebilen varlıklar için bir hareket sistemi yazmamız kolay lakin hareket edebilen ve ateş gücü olan varlıkları çekmek şimdilik mümkün değil. Bu da size bir ödev olsun. Sorgunun tek component yerine n adet component'i sorguya alması yeterli olacaktır.

Şu ana kadar oyun motoru için gerekli birçok unsuru tesis ettik. Varlık oluşturmak, bileşen tanımlayıp varlıklarla ilişkilendirmek, bileşenleri baz alan sistemler tasarlamak ve hatta sorgulamak. Ancak oyun motorunun programcısına sunması gereken durum yönetimini yapan planlayıcı(Scheduler) bileşeni de gerekiyor. Scheduler sınıfının tam olarak yaptığı şey de bu. Bir World nesnesi ile başlatılabiliyor. Oyun dünyasının işleteceği sistemleri state bazlı olarak bir Dictionary'de tutuyor. Scheduler sayesinde programcı tasarladığı sistemleri dahili gelen oyun dünyasına ekleyebiliyor. Run metodunun içeriği ise kayda değer. Temel olarak sistemleri bulup Apply metotlarını işlettiğini ifade edebiliriz. Tabii pek çok handikapı var. Type üstünden reflection ile gittiğinde sistemleri yükleme ve fonksiyon çağırma aksiyonlarının sahne başına yapılması ciddi bir yük. Ancak bunu optimize etmek sonraya bıraktığım ve kabullendiğim bir teknik borç. Henüz ilk denemeyi yapıyoruz. Çalışır bir versiyon elde etmek kritik.

O Zaman Deneyelim

Aslında oyun motoru kabaca hazır. Denemek için oyun programcısı rolüne bürünelim. İlk olarak ihtiyacımız olan bileşenleri(components) tasarlayalım.

namespace NetBevy.Game;

public class Position
    : IComponent
{
    public float X { get; set; }
    public float Y { get; set; }
}

public class Velocity
    : IComponent
{
    public float X { get; set; }
    public float Y { get; set; }
}

public class Range
    : IComponent
{
    public float Value { get; set; }

}

Klasik bileşenlerimiz var. Pozisyon, ivme ve mesafe gibi. Bunlar gerçektende oyundaki bir varlıkla ilişkilendirildiklerinde daha çok anlam kazanıyorlar. Hatta o zaman Query'ler de mantıklı hale geliyor. Hareket edebilen ve mesafe kat edebilen şeyler esasında bu oyun programıcısı açısından Velocity, Range ve Position bileşenleri ile donatılmış varlıklar. Bir kale sadece Position ve Range bileşeni içerirken şehrin giriş kapısı sadece position bileşenine sahiptir. Öyleyse iki de örnek sistem ekleyelim.

namespace NetBevy.Game;

public class SetupPositionSystem : ISystem<Position>
{
    public void Apply(IEnumerable<(Entity entity, Position component)> components)
    {
        foreach (var (entity, position) in components)
        {
            position.X = 0;
            position.Y = 0;
            Console.WriteLine($"[Setup] Entity {entity.ID} initialized at (0,0)");
        }
    }
}

public class MovementSystem : ISystem<Position>
{
    public void Apply(IEnumerable<(Entity entity, Position component)> components)
    {
        foreach (var (entity, position) in components)
        {
            position.X += 1.0f;
            position.Y += 1.0f;
            Console.WriteLine($"[Update] Entity {entity.ID} moved to ({position.X}, {position.Y})");
        }
    }
}

İlk sistem Position bileşeni olan ne kadar varlık varsa onların konumlarını sıfırlıyor. Oyun için anlamsız ama bizim testlerimiz için kafi. MovementSystem isimli sınıf ise Position bileşeni yüklü olan tüm varlıkların X ve Y değerlerini değiştiriyor. Evet çok anlamsız ancak bir önceki cümlede de belirttiğim gibi bunlar bizim sistem testlerimiz. Dikkat edeceğimiz noktalardan birisi her iki sistemin de ISystem arayüzünü implemente etmesi. Dolayısıyla oyun motorunun ihtiyaç duyacağı Apply davranışını uygulamak zorundalar. Oyun programcısı olarak koda baktığımızda bazı şeyler biraz daha net görünüyor. O yüzden artık oyunun kendisini geliştirmek de kolay. Aşağıdaki sınıfı göz önüne alalım.

namespace NetBevy.Game;

public static class GameApp
{
    public static void Run()
    {
        World world = new();

        var player = world.CreateEntity();
        player.AddComponent(new Position { X = 10, Y = 10 });
        player.AddComponent(new Velocity { X = 1, Y = 0 });

        var enemy = world.CreateEntity();
        enemy.AddComponent(new Position { X = 100, Y = 10 });
        enemy.AddComponent(new Velocity { X = -1, Y = 0 });

        var tower = world.CreateEntity();
        tower.AddComponent(new Position { X = 0, Y = 0 });
        tower.AddComponent(new Range { Value = 85 });

        var scheduler = new Scheduler(world);

        scheduler.AddSystem(SystemState.Startup, new SetupPositionSystem());
        scheduler.AddSystem(SystemState.Update, new MovementSystem());

        scheduler.Run(SystemState.Startup);
        for (int i = 0; i < 3; i++)
        {
            scheduler.Run(SystemState.Update);
        }
    }
}

Dünyada üç varlık oluşturup planlayıcıyı kuruyor ve sistemleri ekliyoruz. Startup durumunu bir kez, Update durumunu ise üç kez çalıştırarak varlıkların ardışık adımlarda nasıl güncellendiğini gözlemliyoruz. Ana program kodumuz ise epeyce sade. Bir nevi uçtan uca test fonksiyonumuz diyebilirim.

using NetBevy.Game;

namespace NetBevy;

internal class Program
{
    static void Main()
    {
        // Basic Sample
        GameApp.Run();
    }
}

İşte çalışma zamanı çıktımız.

Daha Neler Yapılabilir?

Aslında planladığımız gibi(en azından benim kafamda) yürüyen iskelet hazır. Bir kütüphane haline getirildiğinde bileşen eklenebilen, sistem tanımlanıp işletilebilen bir oyun motoruna sahibiz fakat elbette çok fazla eksiği ve hatta iyileştirilmesi gereken yerler var. Örneğin;

Query sınıfını geliştirmek gerekiyor. Birden fazla IComponent türevini ele alabilmeli.(Güncel geliştirmeler için BevyDotNet örnek kodlarına bakabilirsiniz. Source Code Generator müdahalesi ile Query sınıf hiç olmazsa 8 bileşene kadar destek verebiliyor)
Sistem davranışlarında oyun dünyasında basit aksiyonları yapabilecek Command bileşen entegrasyonu gerekli. Örneğin bir sistem içerisinde bir varlık oluşturmak World nesnesindeki Entity zincirine bir nesne örneği eklemek demek. Bu kabiliyet kazandırılabilir.
Oyun motorları varlıklarla ilişkilendirilecek asset'ler için bir yönetici mekanizma sunuyor. Zira ses, animasyon akışı, resim gibi birçok asset söz konusu. Bunların bellek dostu olacak şekilde yönetilmesi başlı başına bir mevzu. Örneğin On My Way örneğimizdeki spawn_spaceship metodu Resource olarak bir AssetServer alıyor ve onun load metodu ile yeni bir varlık tanımlanırken ilişkilendiriliyor. Böylece draw mekanizması uzay gemisi varlığı için sahneye ilgili asset'i çizeceğini de biliyor. Büyük çaplı bir oyunda load metodunun gecikmesiz çalışması, gereksiz yere yükleme yapmaması, zaten var ama ihtiyaç yoksa alandan atması gibi düşünülmesi gereken birçok şey var.
Şu anki sürüm sadece terminalden çalışan bir motor vaat ediyor. Ekran çizdirebilmeli, kamerayı 2D veya 3D olma durumuna göre ayarlayabilmeli ve bunları cross-platform sağlarken varsayılan versiyonlarını da programcıya sağlayabilmeli.
Sistemlerin çalışma sırası şu an tamamen eklenme sırasına bağlı. before/after gibi bağımlılık bildirimleriyle deterministik bir sıralama garanti altına alınabilir.
Varlık ve bileşen çıkarma(despawn, RemoveComponent) yeteneği yok. Şu an motor sadece varlık ekleme işlemlerini yapabiliyor. Bir füze menzil dışına çıktığında ya da bir meteor vurulduğunda onu dünyadan silme gerekiyor. Bunu yabana atmayın. Füzeler oluştukça belleği bir anda şişirebilirler ve oyun kitlenebilir(Açıkçası .Net gibi bir ortam yerine bellek güvenliği konusunda çok daha titiz olan Rust bu açıdan her zaman önde bana kalırsa)
Scheduler.Run içerisindeki reflection tabanlı çözümleme her çalıştırmada tekrar tekrar ve tekrar yapılıyor :) Bu maliyet bir Source Generator ya da derleme zamanı kod üretimiyle önemli ölçüde azaltılabilir esasında. İşte bakılacak bir konu daha. Source Generator.
Sistemler arası iletişim için Bevy'deki Message/Event kavramına benzer bir yapı eklenebilir. Oyun başladı veya bitti gibi durumları bildirmek için böyle bir mekanizma epeyce faydalı olur.
ve daha birçok şey...

Bu liste elbette uzatılabilir. Asıl mesele küçük ama çalışan bir çekirdekten yola çıkıp üzerine katman katman eklemek.

Sonuç

Görüldüğü üzere, birkaç arayüz ve reflection tabanlı bir Scheduler ile bile temel bir ECS mimarisinin iskeletini C# tarafında ayağa kaldırmak mümkün. Elbette bu Bevy'nin sunduğu zenginliğin çok gerisinde. Ne paralel çalışan sistemler var, ne asset yönetimi ne de deklaratif bir plugin sistemi. Ama amaç zaten bunları birebir yeniden inşa etmek değildi. Kompozisyon, veri ile davranışın ayrılması ve sorgu(query) tabanlı sistemlerin nesne yönelimli bir dilde nasıl karşılık bulabileceğini elle deneyerek görmekti.

Bir sonraki adımda yapmayı uzun süredir ertelediğim birkaç şey var. Query sınıfını çoklu bileşen destekleyecek şekilde genişletmek, Command deseni ile sistemler içinde güvenli biçimde varlık oluşturmak, silmek ve reflection yükünü bir Source Generator ile derleme zamanına taşımak. Belki bunları da ayrı bir yazıda ele alırım. Böylece geldik bir çalışmamızın daha sonuna. Tekrardan görüşünceye dek hepinize mutlu günler dilerim.

Kod örneklerinin ilk haline github reposundan ulaşabilirsiniz
Ancak devam eden serüvene dahil olmak isterseniz (Örneğin Source Code Generator eklenmiş bir versiyonu görmek) buradaki örneğe de bakabilirsiniz.

Rust ile Basit Bir Key-Value Store Uygulaması

2026-09-01T18:54:00+00:00

Bir programlama dilini öğrenmeye çalışırken bazı kavramları anlamanın en iyi yolu elbette senaryo bazlı pratik yapmaktan geçiyor. Yazıyı yazdığım tarih itibariyle şöyle bir bakıyorum da repolarımın kıyısında köşesinde bu amaçla yazılmış ama unutulmuş denemeler var. Bugün onlardan birisini yazıya döküp tekrar etmeye çalışacağım. Elimdeki konu oldukça sağlam. Çok sık karşımıza çıkan ama üzerine fazla kafa yormadan ilerlediğimizde bize dert çıkarabilecek üç önemli parçası var; eşzamanlılık(concurrency), müşterek kilitleme(mutex) ve çok kullanıcı tarafından ortaklaşa paylaşılmak istenen veri(shared data). Bunları teorik olarak bilmek başka, aynı verinin birden fazla bağlantı tarafından aynı anda değiştirilmeye çalışıldığı bir senaryoda ele alıp test etmek bambaşka. O yüzden basit ama gerçekçi bir problem seçtim; TCP protokolü üzerinden konuşan, verileri bellekte tutan, minik bir key-value store yazmak.

Ortaya kivi-store adında küçük bir Rust projesi çıktı. Neden Kivi ismini kullandığımı çok irdelemeyin. Meyve olarak severim ama K ve V başharflerini nasıl kullansam derken ortaya böyle bir şey çıktı. Belki çok sağlam bir protokol üzerine oturutup, en süratli ve hafifsiklet dağıtık key-value veritabanı olsa meyvenin tonlarında sevimli bir logosu bile olabilirdi. Çok doğal olarak Redis'in milyonda biri kadar iddialı bir çalışma değil elbette. Asıl amaç üretim ortamda kullanılabilecek bir şey üretmek değil, tokio ile asenkron bir TCP sunucusu yazarken paylaşılan durumu(shared state) nasıl güvenli şekilde yöneteceğimizi görmek. Son adımda bunu bir de Docker imajına gömüp herkesin docker run diyerek ayağa kaldırabileceği hale getireceğiz. Asıl testleri kıymetli Alper Konuralp hocam yapacak :D

Genel Mimari

Projenin genel yapısı oldukça basit ve birkaç modülden oluşuyor. Bunları aşağıdaki gibi özetleyebiliriz.

main.rs: ortam değişkenlerini okuyup sunucuyu ayağa kaldırıyor
server.rs: TCP dinleyicisini(listener) açıyor ve gelen her bağlantı için ayrı bir görev(task) başlatıyor
command.rs: istemciden gelen metni SET, GET, REMOVE, LIST gibi komutlara dönüştürüyor(parse)
handler.rs: bir bağlantının yaşam ömrü içerisinde gelen komutları işleyip cevabı(response) yazıyor
store/data.rs: asıl paylaşılan veri yapısı ise burada. Yani key-value çiftlerini tutan DataStore bileşenimiz.

Programın çalışma akışı kabaca şöyle. main.rs içinde .env dosyasından LISTEN_ADDRESS okunuyor ve server::run metodu çağrılıyor. server.rs içindeki döngü her yeni bağlantıyı kabul ettiğinde tokio::spawn ile ayrı bir asenkron görev başlatılıyor ve o bağlantının okuma/yazma işi handler::handle_request'e devrediliyor. Yani her istemci kendi görevinde yaşıyor ama hepsi aynı veri deposuna erişiyor. İşte tam da bu noktada paylaşılan veri(shared data) problemiyle karşılaşıyoruz.(Ne dediğinizi duyar gibiyim. 100 client bağlansın bu uygulama patlar. Lakin amaçlardan birisi de sınırlarda çalıştırıp eksiklerimizi görmek ve Redis gibi sistemleri geliştirenlere bir kez daha saygı duymak)

server modülünün run fonksiyonu, gelen bağlantıları kabul edip her biri için ayrı bir görev başlatıyor;

use crate::handler::handle_request;
use crate::store::DataStore;
use log::info;
use tokio::net::TcpListener;

pub async fn run(address: &str) -> tokio::io::Result<()> {
    let listener = TcpListener::bind(address).await?;
    let store = DataStore::new();

    info!("Server running at {}", address);

    loop {
        let (stream, addr) = listener.accept().await?;
        info!("Client {} connected", addr);
        let store = store.clone();
        tokio::spawn(async move {
            handle_request(stream, store).await;
        });
    }
}

Komut Protokolü

Komutlarımızın çalışma protokolü kasıtlı olarak çok basit tutuldu. Satır satır, boşlukla ayrılmış metin komutları şeklinde ilerliyoruz. Örneğin istemci SET key value komutunu gönderdiğinde, sunucu key ve value'yu alıp DataStore'a kaydediyor. GET key komutu ile değeri alabiliyor, REMOVE key ile silebiliyor ve LIST komutu ile tüm anahtarları listeleyebiliyoruz.

SET key value
GET key
REMOVE key
LIST

command.rs içindeki Command::parse fonksiyonu gelen metni en fazla üç parçaya bölüyor (splitn(3, ' ')). Böylece value kısmında boşluk geçse bile bozulmuyor.

#[derive(Debug)]
pub enum Command {
    Set { key: String, value: String },
    Get { key: String },
    Remove { key: String },
    List,
    Invalid(String),
}

impl Command {
    pub fn parse(input: &str) -> Self {
        let mut parts = input.trim().splitn(3, ' ');
        let cmd = parts.next().unwrap_or("").to_uppercase();

        match cmd.as_str() {
            "SET" => {
                let key = parts.next().unwrap_or("").to_string();
                let value = parts.next().unwrap_or("").to_string();
                Command::Set { key, value }
            }
            "GET" => {
                let key = parts.next().unwrap_or("").to_string();
                Command::Get { key }
            }
            "REMOVE" => {
                let key = parts.next().unwrap_or("").to_string();
                Command::Remove { key }
            }
            "LIST" => Command::List,
            _ => Command::Invalid(cmd),
        }
    }
}

Bilinmeyen bir komut geldiğinde programı patlatmak yerine Command::Invalid dönüyoruz ve hata durumunu tip sisteminin bir parçası haline getiriyoruz. Bu Rust tarafında alıştığımız bir yaklaşım.

Paylaşılan Veriyi Yönetmek: Arc, Mutex, HashMap

Gelelim paylaşılan veriyi nasıl yöneteceğimizi. İşte asıl mevzumuz biraz da bu. DataStore veri yapımız içinde HashMap<String, String> taşıyan ama bunu Arc<Mutex<...>> enstrümanı ile sarmalayan bir bileşen. Aşağıdaki kod parçasında içeriğini bulabilirsiniz.

use std::collections::HashMap;
use std::sync::Arc;
use tokio::sync::Mutex;

#[derive(Clone)]
#[allow(dead_code)]
pub struct DataStore {
    context: Arc<Mutex<HashMap<String, String>>>,
}

#[allow(dead_code)]
impl DataStore {
    pub fn new() -> Self {
        DataStore {
            context: Arc::new(Mutex::new(HashMap::new())),
        }
    }

    pub async fn set(&self, key: &str, value: &str) {
        let mut context = self.context.lock().await;
        context.insert(key.to_string(), value.to_string());
    }

    pub async fn remove(&self, key: &str) -> bool {
        let mut context = self.context.lock().await;
        context.remove(key).is_some()
    }

    pub async fn get(&self, key: &str) -> Option<String> {
        let context = self.context.lock().await;
        context.get(key).cloned()
    }

    pub async fn keys(&self) -> Vec<String> {
        let context = self.context.lock().await;
        context.keys().cloned().collect()
    }
}

Burada önemli olan bazı temelleri hatırlamamızda fayda var.

Arc(Atomic Reference Counting), aynı veriye birden fazla sahibin(owner) güvenli bir şekilde referans tutabilmesini sağlıyor. Rust'ın sahiplik(ownership) modelinde normalde bir değerin tek sahibi olur kuralı var. Arc bu kuralı, referans sayısını atomik olarak takip ederek gevşetiyor. server.rs içinde her yeni bağlantı için store.clone() çağrısı yaptığımızda aslında HashMap'in kendisi kopyalanmıyor, sadece referans sayacı artıyor. Referanslar scope dışına çıktığında Arc otomatik olarak sayacı azaltıyor ve son referans silindiğinde veri de serbest bırakılıyor.
Mutex(Mutual Exclusion) ise aynı anda yalnızca bir görevin(task) veriye erişebileceğini garanti ediyor. .lock().await çağrısı, kilit başka bir görev tarafından tutuluyorsa mevcut görevi bekletiyor(ama iş parçacığını-thread değil. Asenkron bir bekleme söz konusu burada)

Uygulamada dikkat edilmesi gereken bir ayrıntı var. Kullanılan Mutex enstrümanı dikkat edileceği üzere std::sync::Mutex değil, tokio::sync::Mutex. Standart kütüphane ile gelen primitive'lerden olan Mutex senkron çalışıyor ve bu nedenle kilidi tutarken bir .await noktasına girilirse o kilidi tutan iş parçacığı(thread) bloke oluyor ve bu da tokio'nun runtime'ında beklenmedik tıkanmalara yol açabilir. tokio::sync::Mutex ise tamamen asenkron çalışma moduna uyumlu şekilde yazılmış. Kilit meşgulken bekleyen görev, iş parçacığını serbest bırakıp runtime'ın başka görevleri çalıştırmasına izin veriyor. Bu projede kilit tutulan bloklar zaten çok kısa(HashMap üzerinde insert/get/remove) olduğu için pratikte farkın küçük olacağını düşünebiliriz ama alışkanlık olarak asenkron kod içinde asenkron kilit kullanmak daha doğrudur. Tabii bunu bir denemenizi ve gerçeken dediğim gibi olup olmadığını ispatlamanızı şiddetle tavsiye ederim ;)

Bağlantı Başına Bir Görev Meselesi(Task)

tokio::spawn, işletim sistemi seviyesinde yeni bir iş parçacığı(thread) açmaz. Tokio'nun kendi çok iş parçacıklı(multi-threaded) zamanlayıcısında(scheduler) çalışacak hafif bir görev(task - ki sanırım buna bazen "green thread" de deniyor) oluşturur. Yüzlerce istemci bağlansa bile işletim sistemi bunun yükünü hissetmeyecektir çünkü tokio bu görevleri az sayıda gerçek iş parçacığı üzerinde zamanlar. DataStore üzerindeki Arc<Mutex<...>> sayesinde de bu görevlerin hepsi aynı veriye tutarlı biçimde erişebilir.

handler.rs içindeki handle_request fonksiyonu, bağlantı kapanana kadar döngüde okuma yapıp gelen komutu DataStore üzerinde çalıştırır ve cevabı istemci tarafa yine TCP stream üzerinde yazar.

use crate::command::Command;
use crate::store::DataStore;
use log::{error, info};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpStream;

#[allow(dead_code)]
pub async fn handle_request(mut stream: TcpStream, data_store: DataStore) {
    let mut buffer = [0; 1024];
    loop {
        let size = match stream.read(&mut buffer).await {
            Ok(0) => break,
            Ok(n) => n,
            Err(e) => {
                error!("{}", e);
                break;
            }
        };

        info!("Read {}(bytes)", size);

        let request = String::from_utf8_lossy(&buffer[..size]);
        let cmd = Command::parse(&request);

        let response = match cmd {
            Command::Set { key, value } => {
                data_store.set(&key, &value).await;
                "OK\r\n".to_string()
            }
            Command::Get { key } => {
                info!("GET {}", key);
                match data_store.get(&key).await {
                    Some(value) => format!("{}\r\n", value),
                    None => "NOT FOUND\r\n".to_string(),
                }
            }
            Command::Remove { key } => {
                info!("REMOVE {}", key);
                if data_store.remove(&key).await {
                    "OK\r\n".to_string()
                } else {
                    "NOT FOUND\r\n".to_string()
                }
            }
            Command::List => {
                let keys = data_store.keys().await;
                format!("{}\r\n", keys.join("\r\n"))
            }
            Command::Invalid(cmd) => format!("ERROR: Unknown command '{}'\r\n", cmd),
        };

        if let Err(e) = stream.write_all(response.as_bytes()).await {
            error!("{}", e);
            break;
        }
    }
}

Sabit boyutlu 1024 byte veri taşıyacak bir tampon(buffer) kullanılıyoruz. Küçük komutlar için yeterlidir ama gerçek bir üretim sistemi için elbette değişken uzunluklu ya da uzunluk-öncelikli(length-prefixed) bir protokol tercih edilebilir. Bu proje kapsamında amaç protokol tasarımı değil, eşzamanlılık pratiği olduğu için basit tutuldu (Cidden bu amaçla kendi protokolümü yazacak seviyede bilgim olsun isterdim)

Testler

Repoda hem DataStore hem de Command::parse için birkaç birim testimiz var esasında. DataStore testinde bir anahtar-değer çifti ekleyip sonra onu alıyoruz ve beklenen değerle karşılaştırıyoruz. Command::parse testinde ise bir metin komutunu parse edip doğru şekilde ayrıştırıldığını kontrol ediyoruz. Başka birim testler de eklenip kodun güvenilirliği artırılabilir.

#[tokio::test]
async fn test_set_and_get() {
    let data_store = DataStore::new();
    data_store.set("Resilience", "on").await;
    let expected = data_store.get("Resilience").await.unwrap();
    assert_eq!(expected, "on");
}

#[test]
fn test_command_parse() {
    let cmd = Command::parse("SET Connection dataSource=localhost;database=MongoDb");
    match cmd {
        Command::Set { key, value } => {
            assert_eq!(key, "Connection");
            assert_eq!(value, "dataSource=localhost;database=MongoDb");
        }
        _ => panic!("Expected to parse SET command!"),
    }
}

#[tokio::test] makrosunun burada işaret ettiği önemli bir nokta var. DataStore asenkron metotlar barındırdığı için, testin kendisinin de bir tokio runtime içinde çalışması gerekiyor. Sıradan bir #[test] ile .await kullanmaya çalışsaydık derleyici bunu kabul etmeyecektir. Testleri çalıştırmak için bildiğiniz üzere cargo test komutunu kullanıyoruz.

Docker Imajını Oluşturmak

Çalışmamızın son adımında projeyi herkesin kolayca çalıştırabileceği bir hale getireceğiz. Burada amaç uygulamayı container olarak da sunabilmek. Bunun için bilindiği üzere bir Dockerfile dosyasına ihtiyacımız var. İki aşamalı(multi-stage) bir yapı kullanıyoruz. İlk aşamada rust:1.87.0 imajı üzerinden cargo build --release ile derleme yapılıyor. İkinci aşamadaysa sadece derlenmiş binary çok daha küçük olan debian:bookworm-slim imajına kopyalanıyor.

FROM rust:1.87.0 AS builder

WORKDIR /app
COPY . .

RUN cargo build --release

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=builder /app/target/release/kivi-store /usr/local/bin/kivi-store
COPY .env .env

EXPOSE 5555

CMD ["kivi-store"]

Bu sayede son imaj Rust derleyicisini ve ara derleme dosyalarını içermiyor. Onun yerine çalıştırılabilir dosyayı ve gerekli sertifikaları taşıyor. docker-compose.yml ise tek servisli, minimal bir tanımlamadan ibaret.

services:
  kivi-store:
    build: .
    ports:
      - "5555:5555"

İmajı build etmek ve konteynırımızı ayağa kaldırmak için aşağıdaki komutları deneyebiliriz.

# Docker imajını oluşturmak
docker build -t kivi-store .

# docker-compose ile ayağa kaldırmak için
docker-compose up -d

# Eğer kodda bir değişiklik yaparsak container imajını tazelemek gerekir
docker-compose up -d --build

Gerçek Denemeler

Sunucu ayağa kalktıktan sonra herhangi bir TCP istemcisiyle deneme yapabiliriz ancak en güzeli kendi istemcimizi sunmak olacaktır. Bu amaçla bin klasöründe aşağıdaki içeriği sahip programı yazalım.

use std::env;
use std::io::{self, Write};
use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
use tokio::net::TcpStream;

#[tokio::main]
async fn main() -> tokio::io::Result<()> {
    let address = env::var("KIVI_ADDRESS").unwrap_or_else(|_| "127.0.0.1:5555".to_string());
    let mut stream = TcpStream::connect(&address).await?;
    let mut stdin = BufReader::new(tokio::io::stdin()).lines();

    println!("kivi-store istemcisi - {} adresine bağlandı", address);
    println!("Komutlar: SET key value | GET key | REMOVE key | LIST (çıkmak için Ctrl+C)\n");

    loop {
        print!("> ");
        io::stdout().flush()?;

        let line = match stdin.next_line().await? {
            Some(line) if !line.trim().is_empty() => line,
            Some(_) => continue,
            None => break,
        };

        stream.write_all(format!("{}\r\n", line).as_bytes()).await?;

        let mut buffer = [0u8; 1024];
        let n = stream.read(&mut buffer).await?;
        if n == 0 {
            println!("Bağlantı sunucu tarafından kapatıldı.");
            break;
        }
        print!("{}", String::from_utf8_lossy(&buffer[..n]));
    }

    Ok(())
}

İstemci taraf, kivi-store protokolünün doğası gereği(bir istek - request -> bir cevap - response) tamamen senkron bir döngüyle çalışır. Satırı okur ve sonuna \r\n ekleyip gönderir. Ardından cevabı bekler ve sonucu ekrana basar. tokio::io::stdin()'in asenkron satır okuma desteği zaten küfenin(crate) full özellik kümesiyle(feature set) geliyor, dolayısıyla ekstra bir bağımlılık eklemeye de gerek yok.

Şimdi terminalden testlerimize başlayabiliriz.

# Docker imajı ile veya cargo run ile sunucuyu ayağa kaldırdıktan sonra
# İstemciyi işletebiliriz
cargo run --bin client

# İşte birkaç örnek komut
SET Language Rust
SET Framework Tokio
LIST
SET System Linux
GET Language
REMOVE Language
GET Language
NOT FOUND
LIST

İşte çalışma zamanından bir ekran görüntüsü.

Aynı örneği docker-compose üzerinden ayağa kaldırıp denediğimizde de benzer sonuçları almamız gerekiyor.

Bu arada kendi istemcimizi denedik ama şart değil. ncat gibi bir aracı da kullanabiliriz. Ben Windows 11 sistemine chocolatey ile ncat kurdum ve aşağıdaki gibi denedim.

# kurmak için
# choco install nmap

# bağlanmak için
ncat localhost 5555

# sonraki komutlar aynı şekilde çalışıyor

Dağıtım(Deployment)

Diyelimki kıymetli Alper Konuralp hocam ile birlikte yaptığımız yayında bu sunucu uygulamasını docker paketi olarak verip denemesini istiyeceğim. Hoş örneği docker-hub'a yükleyip docker pull ile çekmesini de sağlayabilirim. Ama buna gerek duyulmayacak kadar sıradan bir örneğimiz var. Aşağıdaki komutlarla ilerleyelim.

# Önce temiz bir build alalım
docker build --no-cache -t kivi-store:v0.1.0 .

# Şimdi imajımızı tek bir dosyaya paketleyelim
docker save -o kivi-store-v0.1.0.tar kivi-store:v0.1.0

# Boyut büyük mü? Hiç dert değil sıkıştırıp transfer boyutunu ufaltabiliriz de
# Gzip yoksa yüklemek gerekir. Bende yoktu çikolata yardımıma yetişti
# choco install gzip
docker save kivi-store:v0.1.0 | gzip > kivi-store-v0.1.0.tar.gz

# Alper Hocam'a bu çıktıyı ulaştırdıktan sonra onun da yapması gerekenler var tabii
# Önce imajı yüklemeli
docker load -i kivi-store-v0.1.0.tar
# Eğer zip'li dosya ile gönderildiysek
# gunzip -c kivi-store-v0.1.0.tar.gz | docker load

# Sonra Container'ı ayağa kaldırabilir
docker run -d -p 5555:5555 --name kivi-store kivi-store:v0.1.0

Bakalım neler olacak?

Sonuç

kivi-store, iddialı bir proje olma amacı taşımıyor; amacı, Arc<Mutex<...>> ikilisinin neden birlikte kullanıldığını, tokio::spawn ile açılan görevlerin işletim sistemi iş parçacıklarından farkını ve asenkron kod içinde neden asenkron bir kilide ihtiyaç duyduğumuzu elle deneyerek pekiştirmekti. Ortaya çıkan sonuç, birkaç yüz satırlık küçük bir TCP sunucusu ama içinde paylaşılan durumu(shared state) güvenli yönetmenin temel desenini barındırıyor.

Bir sonraki adım olarak aklımda şunlar var: uzunluk-öncelikli(length-prefixed) bir protokole geçmek, RwLock ile okuma-ağırlıklı senaryoları karşılaştırmak ve belki de basit bir TTL(time-to-live) desteği eklemek. Böylece geldik derlenmiş bir maceramızın daha sonuna. Umarım faydalı olmuştur. Tekrardan görüşünceye dek hepinize mutlu günler dilerim.

Örnek kodlara github üzerinden ulaşmak için tıklayın

Tauri ile Masaüstü Uygulama Geliştirme

2026-08-31T07:45:00+00:00

Mesleğe ilk başladığım yıllarda Web teknolojileri daha yeni yeni yaygınlaşmaya başlamıştı. Java ilk sürümünü yayınlamışken ben daha çok Delphi ile Windows platformunda masaüstü uygulamalar geliştirmekle meşguldüm. Web tabanlı geliştirmenin avantajları bir yana masaüstü uygulamalarda konuk olunan işletim sisteminin gücünden yararlanma, state tutma şansına sahip olabiliyorduk. Elbette zaman içerisinde neredeyse tüm iş modelleri web tabanlı çözümlere geçti. Web 1.0, 2.0, 3.0 derken Internet'in neredeyse tüm altyapısına sızan sayısız JavaScript Framework arasında geçiş yapar olduk. Özellikle cross-platform tabanlı sistemleri düşününce karşımıza farklı hibrit çözümler de çıktı. Chromium gibi tarayıcıların işletim sisteminde çalışabilen çekirdek ara yüzleri ile backend tarafı klasik servis haberleşmeleri üzerinden konuşmaya başladı. Herhalde Electron bu çözümler arasında en bilinenleri arasındadır. Tabii farklı dillerin sunduğu farklı çözümler de var. Örneğin Rust cephesindeki yaklaşımların başında Tauri geliyor. Bir süredir kenara park ettiğim bu konuyu nihayet deneme fırsatı buldum ve öğrendiklerimi bir yazıda toplamak istedim. Amacımız sysinfo küfesini(crate) kullanarak ilkel bir dashboard hazırlamak ve burada en azından CPU, RAM ve Disk kullanımını göstermek.

Tauri Çalışma Modeli

Bir Tauri uygulaması aslında tek bir process'te çalışan iki uygulamadan oluşur. Çekirdek fonksiyonellikler Rust tarafında ele alınırken önyüz tarafında WebView kullanılır. Bu WebView her platformda farklıdır; Linux tarafında WebKitGTK, Windows tarafında Edge WebView2 ve macOS tarafında WKWebView. İşte Electron ile kıyaslandığında ilk fark tam olarak burada ortaya çıkar. Electron kendi Chromium motorunu paketin içinde taşırken, Tauri işletim sisteminde zaten var olan WebView bileşenini kullanır. Bu da paket boyutunda ve bellek tüketiminde ciddi bir fark yaratır.

Ele alacağımız örneği göz önüne alırsak Tauri'nin çalışma prensibini aşağıdaki şekildeki gibi özetleyebiliriz.

Önyüz ve arka plan uygulamaları arasında IPC(Inter Process Communication) mekanizması ile veri alışverişi yapılır. REST gibi network katmanına çıkmayı gerektirecek bir iletişim söz konusu değildir, doğrudan IPC'nin avantajlarından yararlanılır. Önyüz için söyleyebileceğimiz önemli detaylardan birisi de işletim sistemine doğrudan temas etmiyor oluşudur. İhtiyaç duyduğu her şeyi Rust tarafından ister. Bu iletişim de temelde iki enstrüman üzerine kuruludur.

Commands: Javascript veya Typescript tarafından invoke fonksiyonu ile `tauri::command` direktifi ile işaretlenmiş Rust fonksiyonları çağırılabilir. `Request/Response` işleyişi her zaman asenkrondur.
Events: Fire and forget mantığında one-to-many şeklinde bir iletişim söz konusudur. Rust tarafından `tauri::event::emit` ile event yayınlanabilir ve önyüz tarafında `window.listen` ile yakalanabilir.

Aradaki iletişimde hareket eden bilgilerin JSON formatında serileşebilir olması gerekir. Bu da içeride serde küfesinin kullanıldığı anlamına gelir ki yazının ilerleyen kısımlarında bunu bolca göreceğiz.

Kurulumlar

Ben örnek çalışmayı Ubuntu 26.04 üzerinde gerçekleştirdim. Sistemimde zaten Rust, Node.js ve npm kurulu. Ancak bunların haricinde özellikle Linux tarafında `libwebkit2gtk-4.1-dev` paketinin de kurulu olması gerekiyor. Bu paket WebKitGTK'nın geliştirme kütüphanesini içeriyor. Windows tarafında kullanılan WebView2 için ayrıca bir kurulum yapmaya gerek yok, güncel Windows sürümleriyle birlikte geliyor. macOS tarafında ise WKWebView zaten sistemin bir parçası.

# Öncelikle gerekli bazı ortam kütüphanelerini yükleyelim.
sudo apt update
sudo apt install libwebkit2gtk-4.1-dev \
    build-essential \
    curl \
    wget \
    file \
    libxdo-dev \
    libssl-dev \
    libayatana-appindicator3-dev \
    librsvg2-dev

# Tauri'nin kendisi Node'a ihtiyaç duymaz fakat CLI scaffolding ve Vite dev server ihtiyaç duyar.
# Bu nedenle her ihtimale karşı uyumlu bir node versiyonu kurmakta fayda var. Ben nvm kullandım.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts

# Hemen bir kontrol
node --version

Bu paketlerin ne işe yaradığına kısaca bakmakta yarar var. Zira ilk defa karşılaşan birisi için `apt install` satırındaki liste biraz kalabalık görünebilir.

`libwebkit2gtk-4.1-dev` : WebKitGTK'nın geliştirme kütüphanesi. Bir başka deyişle uygulama için önemli olan WebView'ın ta kendisi.
`build-essential` : Rust için C toolchain linker.
`libxdo-dev` : X11 için mouse ve keyboard event'lerini simüle etmek için gerekli kütüphane.
`libssl-dev` : OpenSSL kütüphanesi. Rust tarafında bazı kriptografik fonksiyonlar için gerekli.
`libayatana-appindicator3-dev` : Linux tarafında uygulama ikonları için gerekli kütüphane. System tray desteği.
`librsvg2-dev` : SVG ikonlarının render edilmesi için gerekli kütüphane. Tauri uygulamaları SVG ikonlarını kullanır.

Projenin Oluşturulması ve İlk Gösterim

Projeyi kurmak oldukça basit. Scaffolding için Tauri CLI aracını kullanıyoruz.

npm create tauri-app@latest

CLI arabirimi uygulama ile ilgili bize birkaç soru soracaktır. Bu soruları aşağıdaki gibi cevaplayabiliriz.

Project name: sys-trace(Bu benim verdiğim uygulama adı. Siz başka bir tane verebilirsiniz)
Identifier: com.buraks.sys-trace(Varsayılan olarak sunulanı kabul ettim. Bana biraz Java classpath mantığını hatırlattı)
Choose which language to use for the frontend: Typescript
Choose your package manager: npm
Choose your UI template: Vanilla
Choose your UI flavor: Typescript

Bilerek herhangi bir framework seçmedim. Zira odağımızın React veya Svelte gibi bir tarafa kaymasını şu an için gerek yok. Bu bizim bir nevi *Hello Tauri* uygulamamız. Sonrasında uygulama klasörüne girip gerekli npm paketlerini yükleyebilir ve uygulamanın ilk halini çalıştırabiliriz.

cd sys-trace
npm install

# Uygulamayı çalıştıralım.
npm run tauri dev

Karşımıza aşağıdaki gibi bir pencere çıkması lazım.

İlk çalıştırmada büyük ihtimalle Rust tarafı gerekli küfeleri(crates) yükleyecektir ve bu işlem birkaç dakika sürebilir. Sabırlı olun :D

Proje İskeleti Hakkında Bilgi

Uygulama çalıştığına göre proje içeriğini biraz tanıyalım. Tabii sonraki sürümlerde değişiklikler olabilir.

`index.html` : WebView giriş noktası(entry point)*.
`vite.config.ts` : Tauri development server için Vite konfigürasyonu.
`src` klasörü: Tamamen önyüz tarafı.
`src-tauri` klasörü: Rust tarafı ve ayrı bir crate. Kendi `Cargo.toml` dosyasına sahiptir. Dolayısıyla bu örnekte kullanacağımız sysinfo kütüphanesi de buraya eklenir.
`src-tauri/capabilities` klasörü: Tauri uygulamasının hangi yetenekleri kullanacağını belirten manifest dosyaları(Permission grants)*.
`lib.rs` ve `main.rs` : İş kurallarımız burada yaşar.

Rust tarafında programın çalıştığı sistemden bazı bilgileri toplamak için kullanılan popüler küfelerden birisi sysinfo crate'idir. Bunu `src-tauri` klasöründe aşağıdaki gibi yükleyebiliriz.

cd src-tauri
cargo add sysinfo --no-default-features --features system,disk

Buradaki `--no-default-features` kullanımı bilinçli bir tercih. sysinfo varsayılan olarak process listesi, network arabirimleri, sıcaklık sensörleri gibi pek çok bileşeni de derlemeye dahil ediyor. Bizim ihtiyacımız sadece sistem ve disk bilgileri olduğundan gereksiz yükten kurtulmuş oluyoruz. Sonuçta kullanmayacağımız enstrümanları paket içerisine almak gereksiz bir şişmeye de neden olacaktır. Bu işlemler sonrasında `Cargo.toml` dosyasında gerekli bağımlılıkları görmeliyiz.

[package]
name = "sys-trace"
version = "0.1.0"
description = "A simple system dashboard app written with Tauri"
authors = ["Burak Selim Şenyurt"]
edition = "2021"

[lib]
name = "sys_trace_lib"
crate-type = ["staticlib", "cdylib", "rlib"]

[build-dependencies]
tauri-build = { version = "2", features = [] }

[dependencies]
tauri = { version = "2", features = [] }
tauri-plugin-opener = "2"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sysinfo = { version = "0.39.6", default-features = false, features = ["system", "disk"] }

`[lib]` bölümüne dikkat edelim. Tauri, çekirdek kodu bir kütüphane olarak paketler ve `main.rs` bunu sadece çağırır. Böylelikle aynı kod tabanı mobil hedefler için de kullanılabilir hale gelir.

Rust Tarafındaki Veri Modeli

Şimdi sıra geldi asıl işi yapan kodları yazmaya. Ben Rust tarafını üç parçaya böldüm. Önyüze taşıyacağımız veri modelleri için `metrics.rs`, ölçümleri toplayan fonksiyonlar için `engine.rs` ve Tauri ile buluştuğumuz nokta olan `lib.rs`.

İşe olmazsa olmaz veri modelleriyle başlayalım. `src-tauri/src/metrics.rs` dosyasını aşağıdaki gibi oluşturabiliriz.(Rust dilinde geliştirme yapıyor olsak bile program varlıklarını temsil eden veri modelleri ile çalışmak her zaman iyidir)

use serde::Serialize;

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CpuCore {
    pub name: String,
    pub frequency: u64,
    pub usage: f32,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct MemorySnapshot {
    pub total: u64,
    pub used: u64,
    pub available: u64,
    pub swap_total: u64,
    pub swap_used: u64,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct DiskSnapshot {
    pub name: String,
    pub mount_point: String,
    pub file_system: String,
    pub kind: String,
    pub total_space: u64,
    pub available_space: u64,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Metrics {
    pub global_cpu: f32,
    pub cpu_cores: Vec<CpuCore>,
    pub memory: MemorySnapshot,
    pub disks: Vec<DiskSnapshot>,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct HostInfo {
    pub name: String,
    pub os: String,
    pub kernel_version: String,
    pub architecture: String,
    pub cpu_brand: String,
    pub physical_cores: Option<usize>,
    pub logical_cores: usize,
}

Dosya boyunca tekrar eden iki direktif var. `Serialize`, bu veri yapılarının JSON'a dönüştürülebilmesini sağlıyor ki IPC hattından geçebilmesi için bu şart diyebilirim. `#[serde(rename_all = "camelCase")]` ile belirtilen rename_all değeri ise daha önemli. Rust tarafında `snake_case` yazım tarzını seçiyoruz ve `swap_total` gibi alan adları kullanıyoruz. Typescript tarafında ise `camelCase` daha yaygın bir isimlendirme standardı. Bu direktif sayesinde serileştirme sırasında `swap_total` alanı JSON'a `swapTotal` olarak yazılıyor. Yani iki dünyanın da kendi geleneğine sadık kalabiliyoruz(Biz ayrı dünyaların insanıyız demeye son) Bu arada `physical_cores` alanını `Option<usize>` olarak tanımladığımı fark etmiş olmalısınız. Zira sysinfo, her platformda fiziksel çekirdek sayısını tespit edemeyebilir. Bu bilgi JSON tarafında `null` olarak yer alacak, önyüzde de ona göre bir kontrol yapacağız.

Ölçümleri Toplamak

Veri yapıları hazır olduğuna göre bunları dolduracak fonksiyonları geliştirmeye başlayabiliriz. Bu amaçla `src-tauri/src/engine.rs` isimli bir dosya oluşturup içeriğini aşağıdaki gibi dolduralım.

use crate::metrics::HostInfo;
use crate::metrics::Metrics;
use sysinfo::{Disks, System};

pub fn get_host_info(sys: &System) -> HostInfo {
    let name = System::host_name().unwrap_or_else(|| "Unknown".to_string());
    let os = System::long_os_version().unwrap_or_else(|| "Unknown".to_string());
    let kernel_version = System::kernel_version().unwrap_or_else(|| "Unknown".to_string());
    let architecture = std::env::consts::ARCH.to_string();
    let cpu_brand = sys
        .cpus()
        .first()
        .map_or("Unknown".to_string(), |cpu| cpu.brand().to_string());
    let physical_cores = System::physical_core_count();
    let logical_cores = sys.cpus().len();

    HostInfo {
        name,
        os,
        kernel_version,
        architecture,
        cpu_brand,
        physical_cores,
        logical_cores,
    }
}

`get_host_info` fonksiyonu makine ile ilgili ve çalışma boyunca değişmeyecek bilgileri topluyor. Bu bilgilerin bir kısmına(host adı, işletim sistemi sürümü, kernel sürümü gibi) System türü üzerinden statik fonksiyonlarla erişebiliyoruz. Hepsi `Option<String>` döndürdüğü için `unwrap_or_else` ile makul bir varsayılan değer veriyoruz. Mimari bilgisini ise sysinfo'ya sormaya gerek yok, `std::env::consts::ARCH` sabiti derleme zamanında zaten hedef mimariyi biliyor. Asıl iş yükü ise sürekli çağıracağımız `collect` fonksiyonunda. Bu fonksiyonu da aynı dosyaya ekleyerek devam edelim.

pub fn collect(sys: &mut System, disks: &mut Disks) -> Metrics {
    sys.refresh_cpu_usage();
    sys.refresh_cpu_frequency();
    sys.refresh_memory();
    disks.refresh(true);

    let cpu_cores = sys
        .cpus()
        .iter()
        .map(|cpu| crate::metrics::CpuCore {
            name: cpu.name().to_string(),
            frequency: cpu.frequency(),
            usage: cpu.cpu_usage(),
        })
        .collect();

    let memory = crate::metrics::MemorySnapshot {
        total: sys.total_memory(),
        used: sys.used_memory(),
        available: sys.available_memory(),
        swap_total: sys.total_swap(),
        swap_used: sys.used_swap(),
    };

    let disks = disks
        .iter()
        .map(|disk| crate::metrics::DiskSnapshot {
            name: disk.name().to_string_lossy().to_string(),
            mount_point: disk.mount_point().to_string_lossy().to_string(),
            file_system: disk.file_system().to_string_lossy().to_string(),
            kind: format!("{:?}", disk.kind()),
            total_space: disk.total_space(),
            available_space: disk.available_space(),
        })
        .collect();

    crate::metrics::Metrics {
        global_cpu: sys.global_cpu_usage(),
        cpu_cores,
        memory,
        disks,
    }
}

Fonksiyonun ilk dört satırı konuşmaya değer. sysinfo tembel(lazy) modda çalışır. Yani `sys.total_memory()` çağrısı gerçek zamanlı bir ölçüm yapmaz bunun yerine en son `refresh` sırasında alınan değeri döndürür. Dolayısıyla her ölçüm turunda ilgili bileşenleri açıkça tazelememiz gerekiyor. Burada da yine sadece ihtiyacımız olanları yeniletiyoruz. Söz gelimi `refresh_all` gibi kapsamlı bir çağrı yapsaydık process listesi de dahil pek çok gereksiz bilgi toplanacaktı ki saniyede bir çalışan bir döngüde bunun maliyeti hiç hoş olmaz.

`disks.refresh(true)` satırındaki `true` değeri ise listede artık görünmeyen diskleri koleksiyondan çıkarmak anlamına geliyor. Uygulama çalışırken bir harici bellek takıp çıkardığımızda listenin doğru güncellenmesini istiyorsak bu parametre işimize yarayacaktır.

Küçük bir uyarı da CPU kullanımı hakkında. sysinfo, CPU kullanım yüzdesini iki ölçüm arasındaki farktan hesaplar. Bu nedenle programın ilk ölçümünde çekirdek değerlerinin sıfır çıkması son derece normaldir. İkinci turdan itibaren gerçek değerler görünmeye başlar. Örneğimizde tazeleme aralığı bir saniye olduğu için kütüphanenin beklediği minimum aralığın da epeyce üzerindeyiz. Ben sorun yaşamadım sizin de yaşayacağını düşünmüyorum.

Son olarak `kind` alanı için kullandığımız `format!("{:?}", disk.kind())` ifadesine değinelim. sysinfo, disk türünü `DiskKind` isimli bir enum ile veriyor(HDD, SSD, Unknown)*. Bunu doğrudan serileştirmek yerine `Debug` çıktısını metinsel bilgiye çeviriyoruz. Bu tamamen benim tembelliğimden kaynaklanıyor :D Daha temiz bir yaklaşım olarak `DiskKind` için kendi dönüşüm fonksiyonumuzu yazabilirdik de.

Uygulama Durumu ve Command'ler

Şimdi geldik Rust tarafının Tauri ile buluştuğu yere. `src-tauri/src/lib.rs` dosyasında önce uygulama durumunu tutacak yapıyı tanımlayalım.

mod engine;
mod metrics;

use std::sync::Mutex;
use sysinfo::{CpuRefreshKind, Disks, MemoryRefreshKind, RefreshKind, System};

use crate::metrics::Metrics;

/*
    Uygulamamız çalışırken System ve Disk bilgilerinin sık sık güncellenmesi gerekecek ancak bu iş
    çapraz çağrılarda eş zamanlılık sorunlarına yol açabilir.
    Bu nedenle System ve Disk nesnelerini Mutex ile sarmalayarak eş zamanlı erişimi güvenli hale getiriyoruz.
    Mutex, birden fazla iş parçacığının aynı anda System ve Disk nesnelerine erişmesini engeller
    ve sadece bir iş parçacığına erişim izni verir.

    Command ile işaretlenmiş fonksiyonlar worker thread pool üzerinden çağırıldığı için de
    bu Mutex yapısı, System ve Disk nesnelerine erişimde güvenliği sağlar.
*/
pub struct AppState {
    pub system: Mutex<System>,
    pub disks: Mutex<Disks>,
}

impl AppState {
    fn new() -> Self {
        /*
            Sadece CPU ve bellek bilgilerini izleyeceğiz (track). Diğer sistem bilgilerine ihtiyacımız yok.
            Bu nedenle RefreshKind ile sadece gerekli alanları güncelleyecek şekilde bir yapılandırma yapıyoruz.
        */
        let refresh = RefreshKind::nothing()
            .with_cpu(CpuRefreshKind::everything())
            .with_memory(MemoryRefreshKind::everything());

        Self {
            system: Mutex::new(System::new_with_specifics(refresh)),
            disks: Mutex::new(Disks::new_with_refreshed_list()),
        }
    }
}

Burada üzerinde durulması gereken asıl konu Mutex kullanımı. Neden ihtiyaç duyduğumuz açıklamaya çalışayım. `System` nesnesini her ölçümde yeniden oluşturmak hem maliyetli hem de anlamsız. Zira CPU kullanım yüzdesinin hesaplanabilmesi için bir önceki ölçümün hafızada tutuluyor olması gerekiyor. Dolayısıyla bu nesneyi uygulama ömrü boyunca yaşatmamız lazım. Tauri bunun için `manage` fonksiyonuyla kullanabileceğimiz bir durum(state) mekanizması sunuyor. Ancak command olarak işaretlediğimiz fonksiyonlar bir worker thread havuzu üzerinden çağırıldığından, aynı `System` nesnesine birden fazla iş parçacığından erişim ihtimali doğuyor. `Mutex` ile sarmalayarak bu erişimi güvenli hale getiriyoruz. Rust'ın bize burada bir kolaylık sağladığını da söylemeliyim zira `Mutex` kullanmasak zaten uygulama kodumuz büyük ihtimalle derlenmeyecekti.(Fakat siz bana güvenmeyin ve bunu kendiniz deneyip ispatlayın) `RefreshKind::nothing()` ile başlayıp sadece CPU ve bellek bileşenlerini eklememiz ise `collect` fonksiyonundaki yaklaşımın bir devamı niteliğinde. Bir başka deyişle nesneyi baştan gereksiz bilgi toplamayacak şekilde yapılandırıyoruz.

Sırada önyüzün çağıracağı fonksiyonlar var.

#[tauri::command]
fn get_metrics(state: tauri::State<'_, AppState>) -> Result<Metrics, String> {
    let mut system = state
        .system
        .lock()
        .map_err(|_| " Sys state poisoned".to_string())?;
    let mut disks = state
        .disks
        .lock()
        .map_err(|_| " Disk state poisoned".to_string())?;
    Ok(engine::collect(&mut system, &mut disks))
}

#[tauri::command]
fn get_host_info(state: tauri::State<'_, AppState>) -> Result<metrics::HostInfo, String> {
    let system = state
        .system
        .lock()
        .map_err(|_| " Sys state poisoned".to_string())?;
    Ok(engine::get_host_info(&system))
}

`#[tauri::command]` direktifi ile işaretlenen fonksiyonlar önyüzden `invoke` ile çağırılabilir hale geliyor. Fonksiyon imzasındaki `tauri::State<'_, AppState>` parametresini biz doldurmuyoruz, Tauri bunu çalışma zamanında otomatik olarak enjekte ediyor.(Bir nevi dependency injection gerçekleştiriyoruz diyebilirim)*

Dönüş türü olarak `Result<T, String>` seçilmesinin de bir sebebi var. Bir command `Result` döndürdüğünde Tauri, `Err` durumunu önyüz tarafında bir Promise rejection'a çeviriyor. Böylece Typescript tarafında `try/catch` ile hatayı yakalayabiliyoruz. Hata türü olarak `String` kullanmamızın sebebi serileşebilir olma zorunluluğu. Daha kurumsal bir çalışmada `thiserror` gibi bir küfeyle kendi hata türümüzü tanımlayıp `Serialize` implementasyonunu vermek çok daha şık olacaktır.

Diğer yandan `lock()` çağrısındaki `map_err` kısmına bakmakta da yarar var. Rust'ta bir `Mutex`, kilidi tutan iş parçacığı panic fırlatırsa zehirlenebilir(poisoned duruma geçer) Bu durumda `lock()` çağrısı da hata döner. Uygulamamızın kilitlenmesi yerine önyüze anlamlı bir mesaj göndermeyi tercih ediyoruz.

Nihayetinde uygulamayı ayağa kaldıran `run` fonksiyonunu yazarak devam edelim.

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_opener::init())
        .manage(AppState::new())
        .invoke_handler(tauri::generate_handler![get_metrics, get_host_info])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

`manage` ile oluşturduğumuz `AppState` örneğini Tauri'nin state havuzuna bırakıyoruz. `generate_handler!` makrosu ise önyüzden çağırılabilecek fonksiyonların listesini derleme zamanında oluşturuyor. Buraya eklemeyi unuttuğumuz bir fonksiyonu `invoke` ile çağırmaya kalkarsak çalışma zamanında hata alırız ki bu benim de birkaç kez düştüğüm bir tuzak oldu :D

`main.rs` dosyasını değiştirmemize gerek yok. Scaffolding sırasında gelen haliyle bırakabiliriz.

// Prevents additional console window on Windows in release, DO NOT REMOVE!!
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]

fn main() {
    sys_trace_lib::run()
}

`windows_subsystem = "windows"` özelliği release derlemesinde uygulamanın arkasında bir konsol penceresi açılmasını engeller. Yorum satırındaki uyarıyı ciddiye almakta fayda var.

Konfigürasyon ve İzinler

Rust tarafı bitti ancak önyüze geçmeden önce iki konfigürasyon dosyasına bakmamız lazım. İlki `src-tauri/capabilities/default.json` ve aşağıdaki içeriğe sahip.

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "opener:default"
  ]
}

Tauri 2 ile gelen izin modeli framework'ün önemli özelliklerinden birisi. Uygulamanın hangi pencerede hangi yetenekleri kullanabileceğini açıkça beyan etmek gerekiyor. Makaledeki örneğimizde ekstra bir izne ihtiyaç yok çünkü sistem bilgilerini bir plugin üzerinden değil kendi yazdığımız command bileşenlerinden alıyoruz. Ancak dosya sistemine erişmemiz veya bir shell komutu çalıştırmamız gerekseydi ilgili izinleri buraya eklememiz gerekecekti. Tahmin edeceğiniz üzere permissions tarafı oldukça kritik.

İkinci konfigurasyon dosyası ise `src-tauri/tauri.conf.json`. Pencere boyutları, tema ve güvenlik ayarları burada yapılıyor.

{
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "sys-trace",
  "version": "0.1.0",
  "identifier": "com.buraks.sys-trace",
  "build": {
    "beforeDevCommand": "npm run dev",
    "devUrl": "http://localhost:1420",
    "beforeBuildCommand": "npm run build",
    "frontendDist": "../dist"
  },
  "app": {
    "withGlobalTauri": true,
    "windows": [
      {
        "title": "sys-trace",
        "width": 800,
        "height": 720,
        "minWidth": 560,
        "minHeight": 480,
        "resizable": true,
        "theme": "Dark"
      }
    ],
    "security": {
      "csp": "default-src 'self'; style-src 'self' 'unsafe-inline'"
    }
  },
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/128x128@2x.png",
      "icons/icon.icns",
      "icons/icon.ico"
    ]
  }
}

Ben çok fazla şey değiştirmedim ama gördüğünüz gibi bundle paketine eklenecek simgelerden, build aşamasındaki detaylara kadar birkaç şey var. `csp` ayarı ile WebView'ın sadece kendi kaynaklarına erişmesine izin veriyoruz. `style-src` için `unsafe-inline` eklenmiş durumda çünkü örnekte inline stiller kullanıyoruz. Üretim ortamına çıkacak bir uygulamada bunu kaldırıp stilleri ayrı bir dosyaya taşımak daha doğru olabilir elbette. `build` bölümünde ise Tauri'nin geliştirme sırasında Vite sunucusunu nasıl ayağa kaldıracağı ve paketleme sırasında hangi klasördeki çıktıyı kullanacağı belirtiliyor.

Önyüz Tarafı

Arayüz için Material Web bileşenlerini tercih ettim. Kullanabilmek için önce ilgili paketi npm ile yüklemek gerekiyor. Ben npm dedim ama kuruluma göre yarn veya farklı bir alternatif de tercih edilebilir.

npm install @material/web

Ardından `index.html` içeriğini aşağıdaki gibi düzenleyebiliriz. Burada esas olarak bir grid kullanılıyor ve verilerin yerleşeceği alanları `id` ile işaretliyoruz. Hemen önemli bir notu vurgulayalım. Ezelden beri tasarım konusunda beceriksizimdir ve genelde çok zorlanırım. Aşağıdaki arayüz tasarımını tamamen GPT 5.6 SOL'a yaptırdım. Sadece Rust ile olan ilişkileri kurguladım diyebilirim.

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>System Dashboard</title>
  <script type="module" src="/src/main.ts" defer></script>
</head>

<body>
  <main style="max-width: 1280px; margin: 0 auto; padding: 8px;">
    <div style="display:grid; grid-template-columns: repeat(4, minmax(0, 1fr)); grid-template-rows: repeat(4, auto); gap:8px;">
      <md-elevated-card style="display:block; padding:10px; grid-column: 1 / span 2; grid-row: 1 / span 2;">
        <h2 style="margin: 0;">Summary</h2>
        <h1 id="hostname" style="margin: 6px 0 4px 0;">—</h1>
        <p id="hostmeta" style="margin: 0 0 8px 0;">connecting…</p>
        <div style="display:grid; grid-template-columns: 1fr 1fr; gap:8px;">
          <md-outlined-card style="display:block; padding:8px;">
            <div>CPU</div>
            <div id="cpu-total">—</div>
          </md-outlined-card>
          <md-outlined-card style="display:block; padding:8px;">
            <div>Memory</div>
            <div id="mem-total">—</div>
          </md-outlined-card>
        </div>
        <p id="loadavg" style="margin: 8px 0 0 0;"></p>
      </md-elevated-card>

      <md-elevated-card style="display:block; padding:10px; grid-column: 3 / span 2; grid-row: 1 / span 2;">
        <h2 style="margin: 0 0 8px 0;">CPU Cores</h2>
        <div id="cores"></div>
      </md-elevated-card>

      <md-outlined-card style="display:block; padding:10px; grid-column: 1 / span 4; grid-row: 3 / span 2;">
        <h2 style="margin: 0 0 8px 0;">Memory & Storage</h2>
        <div style="display:grid; grid-template-columns: 1fr; gap:10px;">
          <div>
            <h3 style="margin: 0 0 6px 0;">Memory</h3>
            <div id="memory"></div>
          </div>
          <div>
            <h3 style="margin: 0 0 6px 0;">Storage</h3>
            <div id="disks"></div>
          </div>
        </div>
      </md-outlined-card>
    </div>
  </main>
</body>

</html>

Şimdi `src/main.ts` dosyasına geçelim. Önce Rust tarafındaki veri modellerinin Typescript karşılıklarını tanımlamalıyız. Bu amaçla içeriği aşağıdaki gibi oluşturabiliriz.

import { invoke } from "@tauri-apps/api/core";
import "@material/web/all.js";

const REFRESH_MS = 1000;

type CpuCore = { name: string; usage: number; frequency: number };
type MemorySnapshot = {
  total: number; used: number; available: number;
  swapTotal: number; swapUsed: number;
};
type DiskSnapshot = {
  name: string; mountPoint: string; fileSystem: string; kind: string;
  totalSpace: number; availableSpace: number;
};
type Metrics = {
  globalCpu: number; cpuCores: CpuCore[]; memory: MemorySnapshot;
  disks: DiskSnapshot[];
};
type HostInfo = {
  name: string; os: string; kernelVersion: string; architecture: string;
  cpuBrand: string; physicalCores: number | null; logicalCores: number;
};

Alan adlarının `camelCase` olduğuna dikkat edelim lütfen. Rust tarafında `#[serde(rename_all = "camelCase")]` direktifini kullanmamızın karşılığını burada alıyoruz. `physicalCores` alanının `number | null` olarak tanımlanması da Rust tarafındaki `Option<usize>` tür kullanımının bir karşılığı. Zira Typescript tarafına bu şekilde ifade edebiliriz.

Tabii burada dikkat edilmesi gereken bir konu var. Bu tür tanımlarını elle yazdığımızda iki taraf arasında sessiz bir bağımlılık oluşturmaktayız. Rust tarafında bir alan adını değiştirdiğimizde Typescript tarafı bundan haberdar olmayabilir çünkü değiştirmeyi unutabiliriz ve sorunu ancak çalışma zamanında alacağımız hata sonrası fark edebiliriz. ts-rs veya specta gibi küfeler Rust türlerinden otomatik olarak Typescript tür tanımları üretebiliyorlar. Sonraki denemelerde bu küfeleri ele almayı da düşünebilirsiniz. Kodun devamında birkaç yardımcı fonksiyonumuz bulunuyor. Bunlar veriyi ekranda gösterilebilir hale getirmek için kullandığımız parçalar. Her ikisi de GPT 5.6 SOL tarafından üretildi. Tasarımı beğenmezseniz kabahat bende değil :D

const $ = (id: string) => document.getElementById(id)!;

function gib(bytes: number): string {
  return (bytes / 1024  3).toFixed(1) + " GiB";
}

function band(pct: number): string {
  return pct < 50 ? "calm" : pct < 85 ? "warm" : "hot";
}

function meter(pct: number, label: string, detail: string): string {
  const clamped = Math.min(100, Math.max(0, pct));
  const state = band(clamped);
  const color = state === "calm" ? "#4caf50" : state === "warm" ? "#ff9800" : "#f44336";
  return `
    <div style="display:grid; grid-template-columns: minmax(120px, 1fr) minmax(130px, 1fr) auto; align-items:center; gap:6px; margin-bottom:4px;">
      <div style="overflow:hidden; text-overflow:ellipsis; white-space:nowrap;">${label}</div>
      <md-linear-progress value="${(clamped / 100).toFixed(3)}" style="--md-linear-progress-active-indicator-color:${color};"></md-linear-progress>
      <div style="font-variant-numeric: tabular-nums; white-space:nowrap; font-size:12px;">${detail} · ${clamped.toFixed(1)}%</div>
    </div>`;
}

function coreMeter(c: CpuCore): string {
  const clamped = Math.min(100, Math.max(0, c.usage));
  const state = band(clamped);
  const color = state === "calm" ? "#4caf50" : state === "warm" ? "#ff9800" : "#f44336";
  return `
    <div title="${c.name} · ${c.usage.toFixed(1)}% @ ${c.frequency} MHz" style="display:flex; flex-direction:column; align-items:center; width:20px;">
      <div style="height:92px; width:14px; border-radius:6px; background:#e0e0e0; display:flex; align-items:flex-end; overflow:hidden;">
        <div style="width:100%; height:${clamped}%; background:${color};"></div>
      </div>
      <div style="font-size:11px; margin-top:3px;">${c.name.replace(/^cpu/i, "").trim() || c.name}</div>
    </div>`;
}

`gib` fonksiyonu Rust tarafından byte cinsinden gelen değerleri GiB'e çeviriyor. `band` fonksiyonu ise kullanım yüzdesine göre bir renk bandı belirliyor. Buna göre yüzde ellinin altı yeşil, seksen beşin altı turuncu ve üzeri kırmızı renkte. `meter` yatay bir ilerleme çubuğu üretirken `coreMeter` her CPU çekirdeği için dikey bir sütun üretiyor.(Yani şu tasarımı sanıyorum birkaç gün uğraşsam yapamazdım. Ey yüce EyAy sen neymişsin be abi!)*

Şimdi de gelen veriyi ekrana basan fonksiyonlara bakalım.

function renderMessage(targetId: string, message: string): void {
  $(targetId).innerHTML = `<p>${message}</p>`;
}

function renderHost(info: HostInfo) {
  $("hostname").textContent = info.name;
  const cores = info.physicalCores
    ? `${info.physicalCores} cores / ${info.logicalCores} threads`
    : `${info.logicalCores} threads`;
  $("hostmeta").textContent =
    `${info.cpuBrand} · ${cores} · ${info.os} · kernel ${info.kernelVersion} · ${info.architecture}`;
}

function render(m: Metrics) {
  $("cpu-total").textContent = m.globalCpu.toFixed(1) + "%";
  $("cores").innerHTML = `
    <div style="display:flex; align-items:flex-end; gap:6px; overflow-x:auto; padding-bottom:2px;">
      ${m.cpuCores.map(coreMeter).join("")}
    </div>`;
  $("loadavg").textContent = "";

  const memPct = (m.memory.used / m.memory.total) * 100;
  $("mem-total").textContent = `${gib(m.memory.used)} / ${gib(m.memory.total)}`;
  const swapPct = m.memory.swapTotal
    ? (m.memory.swapUsed / m.memory.swapTotal) * 100
    : 0;
  $("memory").innerHTML =
    meter(memPct, "RAM", `${gib(m.memory.used)} / ${gib(m.memory.total)} · ${gib(m.memory.available)} free`) +
    (m.memory.swapTotal > 0
      ? meter(swapPct, "swap", `${gib(m.memory.swapUsed)} / ${gib(m.memory.swapTotal)}`)
      : "");

  $("disks").innerHTML = m.disks
    .map((d) => {
      const used = d.totalSpace - d.availableSpace;
      const pct = (used / d.totalSpace) * 100;
      const tag = `${d.name} · ${d.mountPoint} · ${d.fileSystem} · ${d.kind}`;
      return meter(pct, tag, `${gib(used)} / ${gib(d.totalSpace)}`);
    })
    .join("");
}

`renderHost` fonksiyonunda `physicalCores` değerinin `null` gelebileceğinin hesaba katıldığını fark etmiş olmalısınız. Değer yoksa sadece mantıksal çekirdek sayısı gösteriliyor. `render` fonksiyonunda ise takas alanı(swap) için de bir kontrol var. Swap tanımlı değilse o satır hiç çizilmiyor. Nihayet en can alıcı kısma geldik. IPC hattının kullanıldığı yer...

async function tick() {
  try {
    render(await invoke<Metrics>("get_metrics"));
  } catch (err) {
    $("hostmeta").textContent = `sampling failed: ${err}`;
    renderMessage("cores", "Unable to fetch processor metrics.");
    renderMessage("memory", "Unable to fetch memory metrics.");
    renderMessage("disks", "Unable to fetch storage metrics.");
  }
  setTimeout(tick, REFRESH_MS);
}

async function start() {
  try {
    renderHost(await invoke<HostInfo>("get_host_info"));
  } catch (err) {
    $("hostmeta").textContent = `could not read host info: ${err}`;
  }
  tick();
}

start();

`invoke<Metrics>("get_metrics")` çağrısındaki metin ifadesi, Rust tarafındaki fonksiyonun adıyla birebir aynı olmak zorunda. Bu da biraz önce değindiğimiz sessiz bağımlılığın bir başka örneği. Generic parametre olarak verdiğimiz `Metrics` türü ise sadece Typescript'in derleme zamanındaki bilgisi. Yani gelen JSON içeriği gerçekten çalışma zamanında doğrulanmıyor. Bu nedenle IPC hattından ne geldiğine dikkat etmemiz gerekiyor. Döngü için `setInterval` yerine `setTimeout` kullanılıyor. Böylece bir sonraki ölçüm ancak mevcut ölçüm tamamlandıktan sonra planlanıyor. `setInterval` kullanmayı tercih etseydik ölçüm herhangi bir sebeple bir saniyeden uzun sürdüğünde çağrıların üst üste binmesi söz konusu olabilirdi. Yine de bunu bir denemekte yarar var.

`start` fonksiyonu değişmeyen host bilgilerini bir kez alıp ekrana yazıyor ve ardından döngüyü başlatıyor. Buradaki hata yakalama bloğu da kayda değer. Rust tarafındaki command'ler `Result` döndürdüğü için `Err` durumu buraya bir exception olarak düşüyor ve en azından kullanıcıya durumla ilgili bir mesaj gösterilebiliyor.

Çalışma Zamanı(Runtime)

Rust tarafındaki geliştirmeler ile önyüz tarafı bittikten sonra çalışır bir örnekle karşılaşmış oldum. Sizde de benzer sonuçların çıkması gerekiyor.

Paketleme(Building)

Uygulama geliştirmelerini tamamladıktan sonra bir `deb` paketi oluşturabiliriz. Bunun için aşağıdaki komutu çalıştırmamız yeterli.

npm run tauri build

# Yukarıdaki işlem sonrasında bundle/deb ve bundle/appImage klasörleri oluşacaktır.
# Bu klasörler altında paketlenmiş uygulamayı bulabiliriz.

# Kurulum da oldukça basittir.
sudo dpkg -i src-tauri/target/release/bundle/deb/sys-trace_0.1.0_amd64.deb
sys-trace

# Ya da AppImage olarak çalıştırabiliriz.
chmod +x src-tauri/target/release/bundle/appimage/sys-trace-0.1.0_amd64.AppImage
./src-tauri/target/release/bundle/appimage/sys-trace-0.1.0_amd64.AppImage

Aynı kod tabanını Windows tarafında da denedim. Rust ve Typescript kodlarında tek bir satır değiştirmeye gerek kalmadı. Yalnız `package.json` içerisine platforma özel CLI paketinin(`@tauri-apps/cli-win32-x64-msvc`) eklenmesi gerekti. Paketleme komutu tamamen aynı. `npm run tauri build` çağrısı bu sefer `deb` yerine `msi` ve `exe` çıktıları üretmeli. Tabii çapraz platform derleme yapmadığımızı, her platformda ayrı ayrı derlediğimizi hatırlatmam gerekiyor. Yani Windows kurulum paketi için bir Windows makineye ihtiyacımız var gibi.

Sonuç

Tauri ile ilk kez bir uygulama geliştirmiş oldum. Tasarım aşamasına kadar yani Rust tarafında kaldığım sürece epey keyifliydi. Yine de zamanın Delphi ve Windows Forms arayüzlerindeki sürükle bırak rahatlığının olmadığını açıkça itiraf etmeliyim. Bileşenleri bir pencereye görerek bırakmakla tasarımı HTML seviyesinde veya karman çorman CSS stilleri ile(her ne kadar modern framework'ler ile bu kolaylansa da) yapmak zorunda kalmak can sıkıcı. Bu macera ile ilgili sonuçları da şöyle bırakalım öyleyse.

Sorumlulukların ayrımı çok net(Seperation of Concerns olmuş diyebilir miyiz?)*. İşletim sistemine dokunan her şey Rust tarafında, görsellik ise tamamen web dünyasında kalıyor. Bu ayrım önyüz tarafında hangi teknolojiyi seçersek seçelim arka planın değişmemesi anlamına da gelmekte ve pek tabii arka planda Rust dilinin güvenli ve yüksek performans vaat eden yapısından faydalanabiliyoruz.
İzin modeli(capabilities) uygulamanın neye erişebileceğini açıkça beyan etmemizi zorunlu kılıyor. Yazılımın güvenliği açısından oldukça değerli.
İki dünya arasındaki tür eşleşmesini bu örnekte elle yaptık ve bu insan hatasına açık. Rust tarafındaki bir alan adı değişikliğinin önyüzü sessizce bozması pekala mümkün. ts-rs veya specta gibi çözümlere bakmakta fayda var.
Bu örnekte veriyi önyüzden istiyoruz yani Command yaklaşımını kullandık. Halbuki metrikleri Rust tarafında bir arka plan thread'inde toplayıp Event ile yayınlamak daha yerinde bir tasarım olabilir ki bu yönde telkinler de var. Böylece güncelleme sıklığını önyüzün insafına bırakmamış oluruz.(Bunu bir sonraki denemeye not alıyorum.)*

Elbette eksikler de var. Uygulamanın bir grafik geçmişi yok bir başka deyişle CPU kullanımının son otuz saniyedeki seyrini göremiyoruz örneğin. System tray desteği eklemedik ki bu tür bir aracın arka planda çalışıp ihtiyaç halinde açılması çok daha mantıklı olacaktır. Network arabirimleri ve process listesi de tamamen kapsam dışında bırakıldı. Bunları tek tek ele almak yerine öncelikle framework'ü tanımaya odaklandığımız bir örnek üzerinde çalıştık diyebilirim. Belki ilerleyen zamanlarda bu eksikleri de tamamlarız.

Böylece geldik bir çalışmamızın daha sonuna. Tekrardan görüşünceye dek hepinize mutlu günler dilerim.

Örnek kodlara github üzerinden ulaşmak için tıklayınız.

Spring Boot ile Basit Bir DDD Projesi

2026-06-20T09:47:00+00:00

Kendimi bildim bileli C# programlama dili ile geliştirme yapıyorum. Hobi amaçlı ilgilendiğim Rust, Zig ve OCaml dillerini saymazsak profesyonel iş hayatım .NET ekosistemi üzerinde geçti. Çok uzun yıllar önce ise Java programlama dilini öğrenmeye çalışmış ve bu vesile ile `Java ile 24 Kahve Molası` isimli bir seri yazmıştım. 2004 yılında yazdığım makaleleri derleyip bir doküman haline de getirmiştim ki buradan erişebilirsiniz. Tabii aradan yıllar yıllar geçti. Yazılım geliştirme dünyası sürekli değişti ama bazı temel kavramlar ve ilkeler hala aynı. Nesne yönelimli dil prensipleri, SOLID ilkeleri, tasarım kalıpları, yazılım mimarileri halen daha programlama dilleri ve platformlara referans oluyor. İş dünyası çözümleri ve kurumsal projeler bu felsefeler üzerine inşa ediliyor. Sözü fazla uzatmadan bu yazıda nelerden bahsedeceğimize gelelim.

Amacım Domain Driven Design(DDD) yaklaşımını yine hafifsiklet bir senaryo ile olabildiğince basit bir şekilde ele almak(CQRS, Event Sourcing, Message Bus gibi konuları sonraya bırakıyorum) ancak bu sefer Java programlama dilini ve Spring Boot Framework kullanacağım. Başlarken Java dilinde duayen olan arkadaşlarımın affına sığınıyorum zira bir C# geliştiricisi personasıyla olaylara yaklaşacağım. Dolayısıyla Java'nın ve Spring Boot'un bazı niş yeteneklerini atlayabilirim. Bu konuda yorumlarla bana ve okurlarımıza destek olabilirsiniz. Öyleyse başlayalım.

Senaryo

Bilgisayar oyunu kiralayabildiğimiz bir sistem üzerinde duracağız. Artık böyle bir devri yaşamıyoruz tabii ki ama zamanında Commodore 64 oyunları kiraladığımızı ve hatta bildiğiniz ya da bilmediğiniz doksanlık müzik kasetlerine oyunlar yüklettiğimizi hatırlıyorum. Öğrenme amaçlı kullanabileceğimiz keyifli bir senaryo olabilir. Tabii Domain Driven Design denince işin içerisine giren bazı önemli unsurlar var. Bunlardan birisi herkesin söz konusu çözüm için kullandığı ortak dil. Denizcilik alanında bir şeyler yazıyorsak kullanacağımız jargon ile oyun geliştirme sahasındaki jargon tamamen farklı olacaktır. Bu jargon genellikle Ubiquitous Language olarak anılır ve program kodu içerisindeki enstrümanların isimlendirilmesinde hayati önem arz eder. Tabii bunu oluşturmak için aslında kullanıcı hikayelerini detaylıca dinlemek ve senaryolaştırmak gerekir. Biz çok basit birkaç cümleyi baz alalım.

Oyunların her biri kataloğumuzda birer isim(Pacman, Super Mario,...) olarak varlığını sürdürür. Mağazamızda oyun kutularından n adet olabilir.
Sistemde abonelerimiz vardır(Bu demoda aboneleri sadece bir ID olarak tanımlayacağız)
Abonelerimiz oyun kiralayabilirler ancak bir kiralama süresi vardır. Kiralanan oyunlar belli bir sürede geri getirilir.
Abone, kiraladığı oyunu geri getirdiğinde kiralama sona erer ve oyun tekrar mağazada kiralanabilir hale gelir. Ama gecikme olursa bu gecikme süresi kadar ekstra ücret ödenir. Örneğin gecikilen gün başına 2.5 TL ceza ödemek gibi.

Bu cümlelerden aslında belli başlı iş kuralları da ortaya çıkar. Örneğin;

Mağaza stoğunda olmayan bir oyun kiralanamaz.
Oyun kiralandığında kullanılabilir oyun sayısı 1 azalır, geri getirildiğinde 1 artar.
Bir kiralama iki kez geri getirilemez.
Gecikme ücreti için şu formül geçerlidir: `gecikme ücreti = gecikilen gün sayısı * 2.5 TL`

Buradaki basit iş kuralları domain model içerisinde yaşar ve asla atlanamaz(No Bypass). Böylece iş kurallarımızın her zaman geçerli olmasını garanti edebiliriz. DDD yaklaşımında domain'i dış etkenlerden izole etmek çok önemlidir. Bana göre domain modelimiz first citizen' dir.

DDD Özeti

DDD daha çok iş modelini kodun tam merkezine yerleştirmeye odaklanmış bir yaklaşımdır. Bu sayede iş kuralları ve mantığı, programın her yerinde tutarlı bir şekilde uygulanabilir. Ayrıca framework, veritabanı ve benzeri altyapı detaylarını dışarıda tutarak iş modelinin bağımsız ve test edilebilir olmasını hedefler. Bu örnek özelinde ele alacağımız kavramları aşağıdaki tablo ile özetleyebiliriz...

Kavram	Ne anlama gelir?	Bizim örneğimizde neye karşılık gelir?
Ubiquitous Language	Tüm ekip (Geliştiriciler, İş Analistleri, Test Uzmanları, vb.) tarafından paylaşılan ortak dil.	Game, Rental, lateFee, returnOn vb
Value Object	Kimliği olmayan, sadece değerleriyle tanımlanan nesneler. Değiştirilemezdirler. (Immutable)	Money, GameId gibi
Entity	Kimliği olan, yaşam döngüsü boyunca değişebilen nesneler.	Game, Rental gibi
Aggregate	Birbirleriyle ilişkili Entity ve Value Object'lerin bir araya gelerek oluşturduğu tutarlı bir bütün.	RentalAggregate, GameAggregate gibi
Aggregate Root	Aggregate'in dış dünya ile olan tek giriş noktasıdır.	RentalAggregate'in root'u Rental, GameAggregate'in root'u Game gibi
Repository	Aggregate'lerin saklanması ve erişilmesi için kullanılan koleksiyon benzeri aggregate yapıları.	RentalRepository, GameRepository gibi
Domain Service	Birden fazla Entity veya Value Object'in etkileşimde bulunduğu karmaşık iş mantığını içeren servisler.	Bu örnekte ele almayacağız.
Application Service	Bir transaction (Use Case) orkestrasyonunu yöneten servis.	RentGameService, GameCatalogService gibi

Proje Mimarisi

Projede oldukça yalın düşünerek hareket edebiliriz ve katmanlı(layered) bir mimari modeli kullanabiliriz. Biraz ucundan da olsa hexagonal mimari ilkelerine göre inşa edebiliriz. Altın kural bağımlılıkların yönünün(Dependency Direction) doğru uygulanması. Örneğin domain paketi sıfır framework bağımlılığına sahip olmalı ki domain modelindeki iş kurallarını çok kısa sürelerde hiçbir dış framework bağımlılığı olmadan değiştirebilelim veya test edebilelim. Bu sayede domain modelimizi daha esnek ve sürdürülebilir bir hale getirebiliriz. Mimari kurguyu kabaca aşağıdaki şekilde olduğu gibi özetleyebiliriz.

Küçük bir not: Ben bu projeyi bir Linux platformunda(Ubuntu 26.04) geliştiriyorum ancak aynı prensipler diğer platformlar için de geçerlidir.

Proje İskeletinin Oluşturulması

Bir .NET geliştiricisi olarak normalde bir solution açıp projeleri tek tek içerisinde oluştururuz. İhtiyacımız olan bağımlılıkları ise projelere göre ekleriz. Java dünyasında bu tür işlemler ve özellikle bağımlılıkların en ideal şekilde tesis edilmesi uzun zamandır Spring Framework gibi araçlarla etkili bir şekilde yapılmakta. Benzer şekilde hareket edeceğiz. Spring Boot proje oluşturma aracı olan Spring Initializr adresini kullanarak uygulama iskeletini ve tüm gereklilikleri hazırlayabiliriz. Ama aynı işlemleri curl komutu ile terminalden de yapabiliriz.

Özellikle kendi sistemimizde hangi Java ve Maven versiyonları olduğuna dikkat etmekte yarar var. Zira versiyon parametleri uyumlu olmalı. Resimde görülen işlemleri curl komutu ile terminalden yapmak istersek de aşağıdaki gibi hareket edebiliriz.

curl https://start.spring.io/starter.zip \
  -d type=maven-project \
  -d language=java \
  -d bootVersion=3.5.15 \
  -d javaVersion=25 \
  -d groupId=com.example \
  -d artifactId=game-rental \
  -d name=game-rental \
  -d packageName=com.example.gamerental \
  -d dependencies=web,data-jpa,postgresql,validation,flyway \
  -o game-rental.zip

unzip game-rental.zip -d game-rental
cd game-rental

Dikkat edileceği üzere proje oluşturulurken bazı bağımlılıklar (dependencies) da ekledik. Hangisini ne için kullandığımızı özetleyelim.

Paket	Ne işe yarar?
Spring Web	REST API geliştirmek için gerekli olan Spring MVC altyapısını sağlar. Tomcat gibi gömülü bir web sunucusu içerir.
Spring Data JPA	ORM (Object-Relational Mapping) işlemleri için gerekli altyapıyı sağlar. JPA (Java Persistence API) standartlarını kullanarak veritabanı işlemlerini kolaylaştırır.
PostgreSQL Driver	PostgreSQL veritabanına bağlanmak için gerekli sürücüyü sağlar.
Spring Validation	Bean Validation API'sini kullanarak veri doğrulama işlemlerini kolaylaştırır.
Flyway	Veritabanı şemasını yönetmek ve sürüm kontrolü sağlamak için kullanılan bir araçtır. Migrations işlemlerini kolaylaştırır.

Proje Oluşturulduktan Sonra Bazı Ayarlamalar

Proje oluşturulduktan sonra PostgreSQL desteği için yeni bir flyway bağımlılığı (dependency) eklememiz de gerekebilir. Bunun için tüm proje ayarlarını içeren `pom.xml` dosyasına aşağıdaki bağımlılığı eklemek yeterli olacaktır. Daha önceden eklediğimiz bağımlılıklar da bu dosyada yer alır.

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
</dependency>x

Eğer projeyi komut satırından oluşturduysak konfigurasyon dosyası(application.properties) YAML formatında oluşmamış olabilir. Bu dosyayı silip `application.yml` isimli yeni bir dosya oluşturup içeriğini aşağıdaki şekilde düzenleyebiliriz.(Dosya `src/main/resources` dizininde olmalıdır) Bu şart değil ancak yml formatında daha okunabilir ve hiyerarşik bir yapı sağladığı için tercih ediyorum. Tabii ki bu tamamen kişisel bir tercih.

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/gamerental
    username: gamerental
    password: secret

  jpa:
    hibernate:
      ddl-auto: validate
    open-in-view: false
    properties:
      hibernate:
        format_sql: true

  flyway:
    enabled: true

logging:
  level:
    org.hibernate.SQL: debug

Dikkat edileceği üzere veritabanı bağlantı bilgisi, hibernate ve flyway ayarları yapılıyor. Bu ayarlara göre JPA(Java Persistence API) nesneleri ORM tarafında hibernate kullanacak ve veritabanı şeması flyway ile yönetilecek. Ayrıca loglama seviyesini debug olarak ayarladık ki SQL sorgularını loglarda görebilelim(Bunu sadece development aşamasında açmak ama üretim ortamında kapatmak iyi bir pratiktir). Son olarak `ddl-auto` değerini validate olarak ayarladık. Bu sayede JPA, uygulama başlatıldığında veritabanı şemasını kontrol edecek ve eğer tablolar eksikse veya hatalıysa uygulama başlatılmayacaktır. Bu sayede veritabanı şemasının her zaman güncel ve doğru olmasını garanti edebiliriz.

Migration Hazırlıkları

Migration işlemleri için `src/main/resources/db/migration` klasöründe `V1__init.sql` isimli bir dosya oluşturalım ve içeriğini aşağıdaki gibi hazırlayalım. Bu basit çalışma için çoğul eki(plural) formatında isimlendirilmiş games ve rentals tabloları yeterli olacaktır.

CREATE TABLE games (
    id               UUID         PRIMARY KEY,
    title            VARCHAR(100) NOT NULL,
    platform         VARCHAR(50)  NOT NULL,
    total_copies     INT          NOT NULL,
    available_copies INT          NOT NULL
);

CREATE TABLE rentals (
    id                 UUID          PRIMARY KEY,
    game_id            UUID          NOT NULL,
    member_id          UUID          NOT NULL,
    rented_on          DATE          NOT NULL,
    due_on             DATE          NOT NULL,
    returned_on        DATE,
    status             VARCHAR(20)   NOT NULL,
    late_fee_amount    NUMERIC(10,2) NOT NULL,
    late_fee_currency  VARCHAR(3)    NOT NULL
);

CREATE INDEX idx_rentals_game_id ON rentals (game_id);

DDD tasarımında her aggregate kendi tutarlı bütünlüğünü korumaktan sorumludur. Genellikle bir aggregate diğer aggregate'lere ID ile referans verir. Bu nedenle herhangi bir foreign key constraint kullanmamıza gerek yok. Böylece aggregate'ler birbirlerinden bağımsız olur ve aggregate root'lar kendi aggregate'lerini yönetebilirler. Zaten foreign key constraint kullandığımızda aggregate'ler DB seviyesinde birbirlerinin yaşam döngüsüne bağımlı hale gelir ve bu DDD tasarımına aykırıdır.

Docker-Compose Olmadan Asla

Pek çok kişisel ve uzun soluklu çalışmamdan alışılageldiği üzere burada da bir docker-compose dosyası ile PostgreSQL veritabanını ve varsa başka gereklilikleri ayağa kaldırmayı tercih ediyorum. İşte `docker-compose.yml` içeriğimiz;

services:

  postgres:
    image: postgres:latest
    container_name: spring-postgres
    environment:
      POSTGRES_USER: johndoe
      POSTGRES_PASSWORD: somew0rds
      POSTGRES_DB: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql
    networks:
      - spring-network

  pgadmin:
    image: dpage/pgadmin4:latest
    container_name: spring-pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: scoth@tiger.com
      PGADMIN_DEFAULT_PASSWORD: 123456
    ports:
      - "5050:80"
    depends_on:
      - postgres
    networks:
      - spring-network

  sonarqube:
    image: sonarqube:community
    container_name: spring-sonarqube
    restart: unless-stopped
    stop_grace_period: 1h
    ports:
      - "9000:9000"
    environment:
      SONAR_ES_BOOTSTRAP_CHECKS_DISABLE: "true"
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_logs:/opt/sonarqube/logs
      - sonarqube_extensions:/opt/sonarqube/extensions

volumes:
  postgres_data:
  sonarqube_data:
  sonarqube_logs:
  sonarqube_extensions:

networks:
  spring-network:
    driver: bridge

Haftasonu yapabileceğiniz türden olan bu tip çalışmalarda ideal bir pratik olduğunu düşünüyorum. İşiniz bitince konteynerleri kapatır veya silersiniz. Tavsiye edeceğim bir diğer alışkanlıksa temiz kod prensiplerine uymak ve teknik borcu en başından itibaren kontrol altına almak. Bu nedenle Sonarqube servisini de docker-compose içerisine ekledim. Sizden sonraki yazılımcıyı düşünerek kod yazın lütfen :D Konteynerleri ayağa kaldırmak için terminalden aşağıdaki komutu kullanabiliriz.

sudo docker-compose up -d

Uygulama Kodlarımız

Artık sırasıyla uygulama içerisindeki gerekli enstrümanları yazmaya başlayabiliriz. Tabii artık Java dünyasındayız. Efsane paket sistemi URL benzeri bir yapıya sahip. Bu proje açısından baktığımızda root paketimiz `com.example.gamerental` şeklinde. Diğer tüm alt modülleri bu paket altına açacağız. Kabaca aşağıdaki gibi bir dizin yapısı oluşturmamız gerektiğini ifade edebiliriz.

Yazıyı çok fazla uzatmaması için kod dosyalarının içeriklerini buraya eklemedim. Dolayısıyla sizi güzel bir mücadele bekliyor. Kodları ve projeyi buradan çekip inceleyebilir veya sıfırdan kendi senaryonuzla yazabilirsiniz. Kod dosyalarına olabildiğince yorum satırı ekledim umarım anlaşılır olur.

C# Geliştiricileri Açısından

Bu çalışma özelinde bir karşılaştırma tablosu da eklemek isterim. Kodları yazarken veya yazdıktan sonra işinize yarayabilir. En azından Java tarafında kullandığımız enstrüman veya kavramlar C# tarafında neye karşlık geliyor özetleyebiliriz.

Mesele	.NET/C#	Java/Spring Boot
Proje oluşturma	dotnet new CLI	Spring Initializr veya curl
Bağımlılık yönetimi	.csproj içinde NuGet	pom.xml içinde Maven
ORM	Entity Framework Core	Spring Data JPA + Hibernate
Migration	EF Core Migrations	Flyway
Value Object	record	record
Entity kimliği	Dahili Guid desteği	UUID sınıfı
Çalıştırma	dotnet run	mvnw spring-boot:run
Test Framework	xUnit, NUnit, MSTest	JUnit 5
Inheritance	`:` operatörü	`extends`
Interface uygulama	`:` operatörü	`implements`
Paket kavramı	GameRental şeklinde namespace	com.example.gamerental şeklinde package
Class Yerleşimi	Bir dosya içinde birden fazla class olabilir	Her class kendi java dosyasında olmalı
Opsiyonel değerler	Nullable reference types, `?` operatörü	`Optional<T>` sınıfı

Bununla birlikte kodlarda Spring Boot dünyasından gelen birçok anotasyon(annotation) kullanımı var. Bunlarla ilgili bir eşleştirmeyi de aşağıdaki tabloda bulabilirsiniz.

Konu	Spring/Java	.NET/C#
Bir şeyin Entity olduğunu belirtmek	`@Entity`	Genelde bir Entity sınıfından türetmek
DB tarafındaki tabloyu belirtmek	`@Table`	`[Table]`
Bir entity alanının identity olduğunu belirtmek	`@Id`	`[Key]`
Bir entity alanının enum olduğunu belirtmek	`@Enumerated`	`[EnumDataType]`
Repository olarak kullanılacağını belirtmek	`@Repository`	Repository deseni ve DbContext
Service olduğunu belirtmek	`@Service`	Tam karşılığı yok sanırım
Transaction yönetimine dahil olduğunu söylemek	`@Transactional`	TransactionScope veya DbContext üzerinden Transaction yönetimi
Doğrulama (Validation)	`@Valid`	`[Required]`, `[Range]` gibi Data Annotation'lar
Üst tür metodunu ezmek	`@Override`	`override` anahtar kelimesi
REST türünden bir controller	`@RestController`	`[ApiController]`
Request mapping	`@RequestMapping`	`[Route]`
Request body	`@RequestBody`	`[FromBody]`
Path variable	`@PathVariable`	`[FromRoute]`
HTTP Post, Get, Put, Delete gibi aksiyonlar	`@PostMapping`, `@GetMapping`, `@PutMapping`, `@DeleteMapping`	`[HttpPost]`, `[HttpGet]`, `[HttpPut]`, `[HttpDelete]`

Arada kaçırdıklarım olabilir ancak Spring Boot çatısının birçok anotasyon ile işimizi kolaylaştırdığını söyleyebilirim. Sanıyorum ki boilerplate kod yazmak zorunda kalmıyoruz.

Çalışma Zamanı

Projeyi tamamladıktan sonraki olası sonuçlarımı paylaşarak devam edelim. Beni en çok düşündüren şeylerden birisi nasıl build alacağım veya çalıştıracağım idi. .NET tarafında dotnet, rust dünyasında cargo gibi tekil araçlara alıştığım için Java tarafındaki maven, gradle gibi araç çokluğu biraz kafa karıştırıcı olabiliyor. Ancak ne nihyatetinde hedefim projeyi çalıştırmak olduğundan detaylarda çok fazla boğulmadan ilerledim ve aşağıdaki maven komutu ile projeyi başlattım. Tabii postgresql konteynerinin çalışır durumda olduğundan emin olmalıyız ve söz konusu komutu projenin kök dizininde işletmeliyiz.

# Derleme için
./mvnw compile

# Doğrudan çalıştırmak için
./mvnw spring-boot:run

Başlangıçta `V1__init.sql` dosyasındaki SQL scriptleri çalışacak ve veritabanında gerekli tablolar oluşturulacaktır. Daha sonra API endpoint'lerine(interfaces katmanındaki Controller sınıflarımız) aşina olduğumuz HTTP isteklerini göndererek uygulama çıktılarını sorgulayabiliriz. İşte birkaç deneme;

Tabii işin gereği kiralanacak oyunlar lazım. Efsanelerden Super Mario'yu kataloğumuza ekleyerek testlere başlayabiliriz.

curl -X POST http://localhost:8080/api/games \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Super Mario",
        "platform": "NINTENDO_SWITCH",
        "totalCopies": 5
      }'

ve şimdi de bir oyun kiralayalım. Tabii tam bir abonelik sistemimiz olmadığı için abone ID bilgisini kendimiz veriyoruz. Game ID değeri içinse bir önceki denemede eklediğimiz ID değerini kullanabiliriz.

curl -s -X POST http://localhost:8080/api/rentals \
  -H 'Content-Type: application/json' \
  -d "{\"gameId\":\"3c23c76e-3902-40c6-8424-366196f669ca\",\"memberId\":\"de4b0278-b1fd-4dc1-a05b-2509107fd49b\",\"rentalDays\":10}"

Şimdide kullanılabilecek oyun kopya sayısını kontrol edebiliriz.

curl -s http://localhost:8080/api/games/3c23c76e-3902-40c6-8424-366196f669ca

Abonemizin oyunu çok sevdiğini ve birkaç gün geç iade ettiğini düşünelim. Bunu simüle etmek için aşağıdaki gibi ilerleyebiriz.

# Önce iade tarihini bugünden 15 sonraya ayarlayalım ki gecikme ücreti oluşsun.
LATE_DATE=$(date -d "+ 15 days" +%F)

# Bu çağrı sonrasında bir gecikme ücreti oluşmasını bekliyoruz.
curl -s -X POST http://localhost:8080/api/rentals/040cf074-9fc2-4480-9cc5-10a258efe7df/return \
  -H 'Content-Type: application/json' \
  -d "{\"returnDate\":\"$LATE_DATE\"}"

# Son olarak oyun bilgilerini tekrar kontrol edelim. Kiralama sona erdiği için kullanılabilir oyun sayısının tekrar 5 olduğunu görmemiz lazım.
curl -s http://localhost:8080/api/games/3c23c76e-3902-40c6-8424-366196f669ca

Son olarak birde dükkana geri dönen bir oyunu tekrar döndürmek istediğimiz almamız gereken Conflict hatasına bakalım.

curl -i -s -X POST http://localhost:8080/api/rentals/040cf074-9fc2-4480-9cc5-10a258efe7df/return \
  -H 'Content-Type: application/json' -d '{}'

Testler

API noktaları sorunsuz çalışıyor gibi ama kurumsal çapta bir projenin olmazsa olmazlarından birisi de elbetteki birim testler(Unit Tests). Birim testler Code Coverage açısından önemlidir. Bu sayede kodun hangi parçalarının test edildiği yani üzerinden geçilerek sağlamasının yapıldığı yüzdesel olarak ölçülebilir ki bu kodun güvenilirliğinin bir garantisidir. Projemizdeki testler `test/java/com/example/gamerental` dizininde yer almaktadır. Örnek olması açısından Game ve Rental nesnelerinin domain bazlı iş kurallarını test ediyoruz. Projedeki tüm testleri çalıştırmak için kök dizindeyken aşağıdaki komutu kullanmamız yeterli.

./mvnw test

Sonarqube ile Kod Taraması

Dilerseniz birde yazdığımız kod tabanının röntgenini çekip projenin sağlık durumunu kontrol edelim. Öncelikle `docker-compose.yml` içerisinde tanımladığımız Sonarqube servisinin çalıştığından emin olalım. Ayarlarımıza göre `localhost:9000` adresine gidip Sonarqube arayüzüne ulaşabiliyorsak her şey yolunda demektir. Sonrasında aşağıdaki adımları takip edebilirz.

`Create a local project` ile ilerleyelim: Project display name ve Project key değerlerini game-rental olarak belirleyebiliriz. Bir değişiklik yoksa Main branch name değerini main olarak bırakabiliriz.
`Set up new code for project` adımında Follows the instance's default seçeneğini işaretleyip Create Project butonuna tıklayalım.
`Analysis Method` adımında birkaç seçenek görebiliriz. Bunlar genellikle uzak kod repolarına bağlanabileceğimiz alternatiflerdir. Biz local ortamda ilerlediğimiz için Locally seçimi ile devam edelim.
`Analyze your project` kısmında öncelikle bir token üretmemiz gerekiyor. Gerçek hayat senarylarında belirli sürelerde token değerinin değiştirilmesi istenir ancak bu eğitim projesinde Expires in seçeneğini No expiration olarak bırakabiliriz. Token değerini oluşturduktan sonra Continue tuşuna basarak devam edelim.
`Run analysis on your project` adımında projemizin Java tabanlı olduğunu belirtmemiz gerekiyor. Örneğimizde build tool olarak Maven kullanıldığı için onu işaretleyebiliriz.

Tüm bu adımları tamamladığımızda terminalden çalıştıracağımız bir komutumuz olacaktır. Bunu yine projenin root klasöründe işletmemiz gerekiyor(Token bilgisi az önce üretilen bilgidir ve siz denerken farklı bir token olacaktır)

mvn clean verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar \
  -Dsonar.projectKey=game-rental \
  -Dsonar.projectName='game-rental' \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=sqp_859e5004eaccc5c0bb1b2a7f3ada6b5b0c26ce54

İşte projenin teknik değerlendirmesine dair ilk MR raporu. Her ne kadar Passed olarak işaretlense de birçok uyarı var.

Ya Sonrası?

Buraya kadar sabırla geldiyseniz ve benzer çıktılara ulaştıysanız sizi tebrik ederim. En azından bu haftasonunu iyi bir şekilde değerlendirmiş olduğunuzu düşünüyorum. Tabii ki bu çalışma benim gibi C# programcıları için başlangıç seviyesinde bir pratik. Dil bağımsız konuşmak gerekirse, DDD yaklaşımının gerçek hayat senaryolarında uygulanması sanıldığı kadar kolay da değil. Özellikle domain büyüdükçe, farklı domain'ler işin içerisine dahil oldukça, iş kuralları karmaşıklaştıkça kurgu giderek zorlaşabiliyor. Örneğin kim aggregate olmalı veya aggregate root olarak düşünülmeli, kim Value Object olmalı, kim Entity olmalı, hangi iş kuralları aggregate içerisinde yaşamalı, hangileri Domain Service içerisinde konuşlanmalı gibi sorulara cevap bulmak kolay değil. Bu nedenle DDD yaklaşımını öğrenmek için bolca pratik yapmak veya uygulandığı açık kaynak projeleri incelemek gerekiyor. Peki bu çalışma üzerine başka neler neler yapabiliriz?

Üye nesnesini gerçek bir aggregate' e dönüştürmek. Örneğin bir üye en fazla 3 kiralama yapabilir gibi bir senaryoyu ele almak.
Domain bazlı event'ler eklemek. GameRented, GameReturned gibi event'ler kurgulayıp örneğin bildirim göndermek veya iki aggregate üzerinden transactional bir senaryo kurgulamak.
İkinci bir bounded context ile çalışmak. Ödeme(Billing) olabilir mesela. Renting diye farklı bir bounded context ile de event'ler yardımıyla haberleşebiliriz. DDD'nin stratejik tasarımını sahada deneyimleriz.
Mapping operasyonları için farklı alternatifler aramak. Örneğin MapStruct gibi bir enstrümanı işin içerisine katabiliriz.

Böylece geldik bir makalemizin daha sonuna. Tekrardan görüşünceye dek hepinize mutlu günler dilerim.

Orjinal repoya ve kodlara github üzerinden erişebilirsiniz