IVEDI işlemcisi motorla doğrudan konuşan istemci-sunucu protokolüdür: bir WebSocket bağlantısı bir motor oturumudur. İstemci GET /ivedi ile yükseltme yapar (oturum çerezi gerekmez), open mesajıyla MASTER login'i ve parolasını verir; ardından execute, prepare / executePrepared, script, fetch ve close ile çalışır. Metin çerçevesi JSON, ikili çerçevesi BSON taşır; yanıt isteğin kodlamasıyla döner. İşlem denetimi (COMMIT, ROLLBACK, SAVEPOINT, SET CATALOG, SET SEARCH_PATH) sıradan SQL deyimleridir. Mesaj sözleşmesinin tamamı NetsimSystemAgent/docs/netsim-system-agent-protokol.md §7'dedir; Python istemcisi ve canlı sınama IVEDI_Code/sqltest/tools/ivedi_client.py ve ivedi_api_test.py. Delphi uygulamaları bu protokole FireDAC sürücüsüyle bağlanır (LIB37\CORE\FireDAC.Phys.IVEDI.pas, DriverID IVEDI; bağlantı parametreleri Server, Port, Path, Database, User_Name, Password, SearchPath, StatementTimeout); motorun kendi istemci katmanı ise EXECUTE STATEMENT ... ON EXTERNAL 'ivedi:sunucu[:port]/veritabanı' ile başka bir ajana ulaşır.

Süreç modeli: multiProcess'te bağlantıyı tutan işçi süreç oturumun motor bağlantısını, açık imleçlerini ve hazırlanmış deyimlerini soket kapanana kadar taşır; soket kapanınca hepsi bırakılır ve açık işlem geri alınır. Oturum, uygulamanın sessionManager'ında doğrulanmış bir oturum olarak açılır: idleTimeout / lifeTime sınırları ve AdminREST SESSIONS sayımı oradan gelir. Her oturum bir işçi süreçtir; çok sayıda kısa istek için oturum açmak yerine durumsuz uç kullanılır.

Durumsuz uç: POST /ivedi/execute. Tek HTTP isteği = aç + çalıştır + commit + kapat; oturum ve imleç yoktur. Gövde JSON ya da BSON (Content-Type: application/bson), yanıt aynı kodlamayla; kimlik Basic ya da gövdedeki login / password. Alanlar sql, params, database, maxRows (fazlası truncated), script (çok deyimli betik, hatalar toplanır), statementTimeoutMs. Hatasız istek commit edilir, hatalı istek geri alınır; SQL hatası da 200 + ok: false ile döner, yalnız kimlik reddi 401'dir. Aynı kapı geçerlidir: SYSADMIN ya da SYSDBA.

Olaylar. Motorun POST_EVENT '<ad>' [USING (...)] deyimi COMMIT'te ajanın mesaj kuyruğuna /event/<VERİTABANI>/<ad> konusuyla yayınlanır; bir IVEDI oturumu subscribe ile (ad ya da *) abone olur ve olayı sunucu kaynaklı bir çerçeve olarak alır (notification: "event", gövdede ad, veritabanı ve parametreler). Aynı kuyruk /message ucundan da okunabilir; ROLLBACK yayınlamaz.

SQL izleme. subscribe event: "trace" ile abone olan oturum, ajanın bütün oturumlarında koşan her üst düzey deyimin olayını canlı alır (notification: "trace"): zaman, veritabanı, login, bağlantı, deyim türü (query, command, block, ddl, privilege, transaction, compile), metin, parametre sayısı (değerler gönderilmez), süre, ilk sayfadaki satır sayısı, eklenen / güncellenen / silinen satır, hata ve depolama motoruna giden SQL metinleri. Süzgeç: login, database, kind, minMs. Olaylar saklanmaz; abone yokken üretilmez. Yönetim arayüzünde İzleme → SQL izleme sayfası, msql'de --trace / \trace aynı akışı gösterir.

5.5.1 Dil sunucusu kipi (mode: "lsp")

open mesajında mode: "lsp" verilirse oturum MQL metnini hedef lehçeye çeviren dil sunucusu olur: bağlantı #mode convert to <target> kipinde (target, öndeğer postgresql), veritabanının yerleşik GUEST kimliğiyle ve kip kilidiyle çalışır - DML ve DDL yalnızca metne çevrilir, çalıştırılmaz; bu yüzden SYSADMIN rolü istenmez, geçerli bir MASTER login'i yeter. database kayıt adıdır (boş = MASTER), searchPath verilmezse netsim, eklenti, public uygulanır. Çevrim script ile istenir; yanıtın results[] öğeleri çevrilmiş deyimler (sql / text), uyarılar ve hatalardır (error: SQLSTATE, satır, sütun, deyim); errorCount sıfır değilse çıktı kullanılmamalıdır.

Geliştirme kipi (development: true) tasarım zamanı içindir: kayıtlı bir veritabanına bağlanmak yerine oturuma özel bir bellek içi katalog kurulur, oturumun ilk script'i bootstrap: true ile şemayı o kataloğa yazar ve bağlantı ardından çevrim kipine geçip kilitlenir; oturum kapanınca katalog düşer. Bu kip conf'ta lspDevelopmentMode ile açılır (öndeğer kapalı): bootstrap betiği DDL koşturur - kendi bellek içi kataloğunda ve CREATE / DROP DATABASE reddedilerek, ama koşturur - bu yüzden üretim ajanında kapalı durur.

5.5.2 Hata ayıklama (debug)

Bir IVEDI oturumu kendi deyimlerinin PSQL kodunu (saklı yordam, fonksiyon, paket gövdesi, tetikleyici, EXECUTE BLOCK, betik) durma noktasında durdurur, adım adım yürütür, çağrı yığınını ve değişkenleri okur, istisnada durur. Kapı iki katlıdır: uygulamanın debugMode anahtarı açık olmalı ve login MASTER'da DEBUGGER rolünü taşımalıdır (grant "DEBUGGER" to <login>; SYSDBA muaftır; rol veritabanı hakkı vermez, SYSADMIN'e içkin değildir). İzin open yanıtının capabilities listesinde "debug" olarak görünür.

Akış: debug action: "enable" ile açılır, setBreakpoints ile nesne (ŞEMA.AD, satırlar nesnenin CREATE metnine göre 1 tabanlı) ya da betik için durma noktaları konur; deyim koşarken motor bir durma noktasına gelince sunucu aynı sokete notification: "debug", state: "stopped" çerçevesini yazar (çağrı yığını frames ile), istemci aynı soketten variables / evaluate / stepOver / stepInto / stepOut / continue / terminate gönderir. Koşan bir deyim POST /ivedi/debug ({connectionId, cancelKey, action: "pause"}, iptal ucunun sözleşmesi) ile bir sonraki PSQL deyiminde durdurulur. Duraklama boyunca işlem ve kilitler açık kalır, deyim süre sınırı askıdadır; bağlantı koparsa deyim sonlandırılır. Komut ve çerçeve alanları protokol belgesi §7.10'dadır.

5.5.3 Başarım

Ölçüm ivedi_api_test.py --only-bench --workers multiProcess|multiThread ile yapılır (Debug ajan, Python istemci, yerel ağ, 10.000 düz satırlık ve 1.000 satır x 2 KB blob'lu tablo, 20 eş zamanlı oturum). Bir kurulumu değerlendirirken bu sayılar ölçek verir:

Okuma: BSON düz satırda JSON'dan büyüktür (satır dizisinin her öğesine anahtar, tip ve uzunluk yazar), yalnız ikili değer taşıyan sonuç kümelerinde küçüktür (base64 payı yoktur); süre farkı yoktur. Öndeğer JSON kalır, blob taşıyan sorgularda BSON seçilir. İki işçi modeli deyim başına aynı hızdadır: multiThread'de etkin bir WebSocket bağlantısı kendi iş parçacığında kalır ve ancak 200 ms çerçeve gelmezse park edilir; park edilen bağlantıyı dinleyici döngüsü 1 ms adımla yoklar. multiProcess'te oturum açmak daha pahalıdır (bağlantı başına bir işçi süreç); kısa, tek seferlik istekler için durumsuz POST /ivedi/execute ucu vardır, çok sayıda küçük yazma işi tek istekte toplanır (script, Array DML).