Çalışma Zamanı Olayları

Surfnet çalışma zamanı, işlem işleme, slot tikleri, hesap akışı, zaman yolculuğu ve hataları kapsayan yapılandırılmış bir olay akışı yayar. SDK bu akışı açığa çıkarır; böylece testler günlükleri ayrıştırmadan çalışma zamanı davranışını doğrulayabilir.

Rust: Kanal Alıcısı

Surfnet::events(), çalışma zamanının yayımladığı crossbeam_channel::Receiver<SimnetEvent>'e bir referans döndürür. try_iter() ile tüketin (engellemesiz) ya da recv() / recv_timeout() ile olayları tek tek okuyun.

use surfpool_sdk::{SimnetEvent, Surfnet};

let surfnet = Surfnet::start().await?;

// Drain whatever has accumulated so far.
for event in surfnet.events().try_iter() {
    match event {
        SimnetEvent::TransactionProcessed(_ts, metadata, error) => {
            println!("tx {} -> {:?}", metadata.signature, metadata.logs);
            if let Some(err) = error {
                eprintln!("  failed: {err:?}");
            }
        }
        SimnetEvent::ErrorLog(_ts, message) => {
            eprintln!("runtime error: {message}");
        }
        other => {
            println!("event: {other:?}");
        }
    }
}

Alıcı paylaşımlıdır

Olayları tüketmek için arka planda bir görev başlatırsanız, aynı zamanda ana iş parçacığından try_iter çağırmayın. Olaylar iki tüketici arasında tahmin edilemez biçimde bölünür.

JS: Drain Yöntemi

JS bağlamaları olayları dahili olarak arabelleğe alır ve drainEvents aracılığıyla sunar. Her çağrı, önceki çağrıdan bu yana birikmiş olanları döndürür ve ardından arabelleği temizler.

import { Surfnet } from "@solana/surfpool";

const surfnet = Surfnet.start();
try {
  // ... do test setup that triggers events ...

  const events = surfnet.drainEvents();
  for (const event of events) {
    switch (event.kind) {
      case "transactionProcessed":
        console.log("tx", event.transactionSignature, event.logs);
        break;
      case "errorLog":
        console.error("runtime error:", event.message);
        break;
      default:
        console.log(event.kind, event.message ?? "");
    }
  }
} finally {
  surfnet.stop();
}

Sınırsız arabellek

drainEvents hiç çağırmazsanız, arabellek örneğin ömrü boyunca büyür. Kısa testler için sorun değildir, ancak belleğin şişmemesi için uzun süre çalışan fixture'larda periyodik olarak çağırın.

SimnetEventValue Yapısı (JS)

JS olay türü, bir kind ayrıştırıcısına ve isteğe bağlı alanlara sahip düz bir nesnedir. Her varyant için her alan ayarlanmaz — kind değerine göre yapısöküm yapın.

interface SimnetEventValue {
  kind: string; // discriminator, e.g. "TransactionProcessed"
  message?: string; // human-readable message
  timestamp?: string; // ISO timestamp

  // startup
  initialTransactionCount?: number;
  clock?: ClockValue;

  // slot / clock
  epochInfo?: EpochInfoValue;
  clockCommand?: string;
  slotIntervalMs?: number;

  // accounts
  accountPubkey?: string;

  // transactions
  transactionSignature?: string;
  logs?: string[];
  computeUnitsConsumed?: number;
  fee?: number;

  // errors
  errorMessage?: string;

  // misc
  tag?: string;
  profileKey?: string;
  profileSlot?: number;
  runbookId?: string;
  runbookErrors?: string[];
}

Olay Türleri

JS tarafındaki tür dizeleri camelCase; eşleşen Rust varyantı PascalCase kullanır. Bu tam dizeleri eşleştirin — büyük/küçük harfe duyarlıdır ve sürümler arasında sabittir.

JS `kind`	Rust varyantı	Ne zaman yayılır
`ready`	`SimnetEvent::Ready`	Çalışma zamanı başlatmayı tamamlar; `initialTransactionCount` taşır.
`connected`	`SimnetEvent::Connected`	Yukarı akış uzak RPC'ye bağlandı; `message` (URL) taşır.
`aborted`	`SimnetEvent::Aborted`	Başlatma iptal edildi; `message` (neden) taşır.
`shutdown`	`SimnetEvent::Shutdown`	Düzgün bir kapatma işlemi başlar.
`systemClockUpdated`	`SimnetEvent::SystemClockUpdated`	Sistem saati ilerledi; `clock` taşır.
`clockUpdate`	`SimnetEvent::ClockUpdate`	Bir saat komutu çalıştı (duraklat/devam ettir/aralığı güncelle); `clockCommand` ve isteğe bağlı olarak `slotIntervalMs` taşır.
`epochInfoUpdate`	`SimnetEvent::EpochInfoUpdate`	Yeni bir epoch bilgi anlık görüntüsü mevcut; `epochInfo` taşır.
`blockHashExpired`	`SimnetEvent::BlockHashExpired`	Kullanımda olan bir blok karması süresi doldu.
`transactionReceived`	`SimnetEvent::TransactionReceived`	Bir işlem kuyruğa alındı; `timestamp`, `transactionSignature` taşır.
`transactionProcessed`	`SimnetEvent::TransactionProcessed`	Bir işlem yürütüldü; `timestamp`, `transactionSignature`, `logs`, `computeUnitsConsumed`, `fee` taşır ve başarısızlık durumunda `errorMessage`.
`accountUpdate`	`SimnetEvent::AccountUpdate`	Bir hesap değişti — akışa alınan hesapları ve hile kodu kaynaklı mutasyonları kapsar; `timestamp` ve `accountPubkey` taşır.
`infoLog` / `warnLog` / `errorLog` / `debugLog`	`SimnetEvent::InfoLog` / `WarnLog` / `ErrorLog` / `DebugLog`	Çalışma zamanı bir günlük satırı yaydı; `timestamp` ve `message` taşır.
`pluginLoaded`	`SimnetEvent::PluginLoaded`	Bir Geyser eklentisi yüklendi; `message` (eklenti adı) taşır.
`taggedProfile`	`SimnetEvent::TaggedProfile`	Bir profil oluşturma sonucu etiketlendi; `tag`, `profileKey`, `profileSlot`, `logs`, `computeUnitsConsumed` taşır.
`runbookStarted` / `runbookCompleted`	`SimnetEvent::RunbookStarted` / `RunbookCompleted`	Bir runbook başladı veya tamamlandı; `runbookId` ve (tamamlanınca) isteğe bağlı `runbookErrors` taşır.

Assertion Kalıpları

Bir İşlemin Tamamlandığını Doğrula

import { Surfnet } from "@solana/surfpool";

const surfnet = Surfnet.start();
try {
  const sig = await sendTransaction(surfnet.rpcUrl /* ... */);
  // ... wait for confirmation via RPC ...

  const landed = surfnet
    .drainEvents()
    .some(
      (e) => e.kind === "transactionProcessed" && e.transactionSignature === sig
    );

  console.assert(landed, "expected transaction to land");
} finally {
  surfnet.stop();
}

Çalışma Zamanı Hatası Oluşmadığını Doğrula

use surfpool_sdk::{SimnetEvent, Surfnet};

let mut surfnet = Surfnet::start().await?;

// ... run the test ...

let errors: Vec<_> = surfnet
    .events()
    .try_iter()
    .filter(|e| matches!(e, SimnetEvent::ErrorLog(_, _)))
    .collect();

assert!(errors.is_empty(), "runtime errors: {errors:?}");

surfnet.stop()?;

Olaylar Neden Log Ayrıştırmasından Üstündür

stdout Yerine Olay Akışını Tercih Edin

Çalışma zamanı, tracing aracılığıyla yapılandırılmış olaylar yazdırır; bu olayları stdout'tan yakalayıp ayrıştırmak cazip gelebilir. Yapmayın. Yapılandırılmış olay akışı:

Log seviyesi değişikliklerine karşı dayanıklıdır — olaylar, RUST_LOG değerinden bağımsız olarak yayılır.
Türlendirilmiş yüklerle gelir — string ayrıştırma yok, sürümler arasında format kayması yok.
Kararlı türlere sahiptir — log satırları insanlar için biçimlendirilir ve serbestçe değişir; olay türleri SDK sözleşmesinin bir parçasıdır.

İçindekiler