მოვლენათა ავტობუსი

PRX მოვლენათა ავტობუსი დანამატებსა და ჰოსტ სისტემას შორის კომუნიკაციას თემაზე დაფუძნებული გამოქვეყნება/გამოწერის მექანიზმით უზრუნველყოფს. დანამატებს შეუძლიათ მოვლენების გამოქვეყნება, თემებზე გამოწერა და სიცოცხლის ციკლის მოვლენებზე რეაგირება -- ყველაფერი კომპონენტებს შორის პირდაპირი კავშირის გარეშე.

მიმოხილვა

მოვლენათა ავტობუსი უზრუნველყოფს:

• თემაზე დაფუძნებული მარშრუტირება -- მოვლენები იერარქიულ თემებზე ქვეყნდება და შესაბამის გამომწერებს მიეწოდება
• სიმბოლოანი გამოწერები -- თემის მთლიანი ქვეხეების გამოწერა glob-სტილის შაბლონებით
• დატვირთვის ლიმიტები -- მაქსიმუმ 64 KB მოვლენის დატვირთვაზე რესურსების ბოროტად გამოყენების თავიდან ასაცილებლად
• რეკურსიის დაცვა -- მოვლენით-გამოწვეული-მოვლენის მაქსიმუმ 8 დონის სიღრმე უსასრულო ციკლების თავიდან ასაცილებლად
• არა-უმეტეს-ერთხელ მიწოდება -- მოვლენები გამომწერებს მიეწოდება პერსისტენციისა და ხელახალი ცდის გარეშე

თემის სტრუქტურა

თემები იერარქიულ, წერტილით გამოყოფილ სახელდებას მიჰყვება prx. სახელთა სივრცის ქვეშ:

prx.<კატეგორია>.<მოვლენა>

ჩაშენებული თემები

თემა	გამომქვეყნებელი	აღწერა
prx.lifecycle.started	ჰოსტი	PRX დაიწყო და ყველა კომპონენტი ინიციალიზებულია
prx.lifecycle.stopping	ჰოსტი	PRX ითიშება; დანამატებმა გასუფთავება უნდა მოახდინონ
prx.lifecycle.config_reloaded	ჰოსტი	კონფიგურაცია ცხელ რეჟიმში ხელახლა ჩაიტვირთა
prx.session.created	ჰოსტი	ახალი აგენტის სესია შეიქმნა
prx.session.terminated	ჰოსტი	აგენტის სესია შეწყდა
prx.session.message	ჰოსტი	შეტყობინება გაიგზავნა ან მიიღეს სესიაში
prx.channel.connected	ჰოსტი	არხმა კავშირი დაამყარა
prx.channel.disconnected	ჰოსტი	არხმა კავშირი დაკარგა
prx.channel.error	ჰოსტი	არხმა შეცდომა წააწყდა
prx.tool.before_execute	ჰოსტი	ინსტრუმენტი შესრულების წინ დგას (ინტერცეპტირებადია)
prx.tool.after_execute	ჰოსტი	ინსტრუმენტის შესრულება დასრულდა
prx.plugin.loaded	ჰოსტი	დანამატი ჩაიტვირთა
prx.plugin.unloaded	ჰოსტი	დანამატი ამოიტვირთა
prx.evolution.proposed	ჰოსტი	თვით-ევოლუციის წინადადება წარმოიქმნა
prx.evolution.applied	ჰოსტი	თვით-ევოლუციის ცვლილება გამოყენებულ იქნა
prx.evolution.rolled_back	ჰოსტი	თვით-ევოლუციის ცვლილება უკუქცეულ იქნა
prx.memory.stored	ჰოსტი	მეხსიერების ჩანაწერი შეინახა
prx.memory.recalled	ჰოსტი	მეხსიერებები კონტექსტისთვის გახსენდა
prx.cron.tick	ჰოსტი	cron პულსი მოხდა

მორგებული თემები

დანამატებს შეუძლიათ საკუთარი სახელთა სივრცის ქვეშ მორგებულ თემებზე გამოქვეყნება:

prx.plugin.<plugin_name>.<event>

მაგალითად, ამინდის დანამატმა შეიძლება გამოაქვეყნოს:

prx.plugin.weather.forecast_updated
prx.plugin.weather.alert_issued

გამოწერის შაბლონები

ზუსტი დამთხვევა

ერთ კონკრეტულ თემაზე გამოწერა:

event_bus.subscribe("prx.session.created", handler);

სიმბოლოანი დამთხვევა

ქვეხის ყველა თემაზე გამოწერა * (ერთ დონე) ან ** (მრავალ დონე) გამოყენებით:

// ყველა სესიის მოვლენა
event_bus.subscribe("prx.session.*", handler);

// ყველა სიცოცხლის ციკლის მოვლენა
event_bus.subscribe("prx.lifecycle.*", handler);

// კონკრეტული დანამატის ყველა მოვლენა
event_bus.subscribe("prx.plugin.weather.*", handler);

// ყველა მოვლენა (ეკონომიურად გამოიყენეთ)
event_bus.subscribe("prx.**", handler);

შაბლონი	ემთხვევა	არ ემთხვევა
prx.session.*	prx.session.created, prx.session.terminated	prx.session.message.sent
prx.session.**	prx.session.created, prx.session.message.sent	prx.channel.connected
prx.*.connected	prx.channel.connected	prx.channel.error
prx.**	ყველაფერი prx.-ის ქვეშ	prx. სახელთა სივრცის გარეთ თემები

მოვლენის სტრუქტურა

ყოველი მოვლენა შეიცავს:

ველი	ტიპი	აღწერა
topic	String	თემის სრული ბილიკი (მაგ., prx.session.created)
payload	Vec<u8>	სერიალიზებული მოვლენის მონაცემები (კონვენციით JSON, მაქს. 64 KB)
source	String	გამომქვეყნებლის იდენტობა (მაგ., host, plugin:weather)
timestamp	u64	Unix დროის ნიშანი მილიწამებში
correlation_id	Option<String>	არასავალდებულო ID დაკავშირებული მოვლენების თვალთვალისთვის

დატვირთვის ფორმატი

დატვირთვები კონვენციით JSON-ად სერიალიზდება. ყოველი თემა საკუთარ დატვირთვის სქემას განსაზღვრავს. მაგალითად:

prx.session.created:

{
  "session_id": "sess_abc123",
  "channel": "telegram",
  "user_id": "user:telegram:123456789"
}

prx.tool.after_execute:

{
  "session_id": "sess_abc123",
  "tool_name": "shell",
  "command": "ls -la /tmp",
  "duration_ms": 45,
  "success": true
}

კონფიგურაცია

[plugins.event_bus]
enabled = true
max_payload_bytes = 65536           # 64 KB
max_recursion_depth = 8             # უსასრულო მოვლენათა ციკლების თავიდან აცილება
max_subscribers_per_topic = 64      # გამომწერთა ლიმიტი თემაზე
channel_capacity = 1024             # შიდა მოვლენათა რიგის ტევადობა
delivery_timeout_ms = 5000          # ნელი გამომწერებისთვის ვადაგასვლა

კონფიგურაციის მითითება

ველი	ტიპი	ნაგულისხმევი	აღწერა
enabled	bool	true	მოვლენათა ავტობუსის ჩართვა ან გამორთვა
max_payload_bytes	usize	65536	მოვლენის დატვირთვის მაქსიმალური ზომა (64 KB)
max_recursion_depth	u8	8	მოვლენით-გამოწვეული-მოვლენის ჯაჭვების მაქსიმალური სიღრმე
max_subscribers_per_topic	usize	64	გამომწერთა მაქსიმალური რაოდენობა ზუსტ თემაზე
channel_capacity	usize	1024	მოვლენათა რიგის შემოსაზღვრული არხის ტევადობა
delivery_timeout_ms	u64	5000	მაქსიმალური დრო გამომწერის მოვლენის დამუშავებისთვის

მოვლენათა ავტობუსის გამოყენება დანამატებში

PDK (დანამატის განვითარების ნაკრები)

PRX PDK WASM დანამატებში მოვლენათა ავტობუსთან ურთიერთქმედების დამხმარე ფუნქციებს უზრუნველყოფს:

use prx_pdk::event_bus;

// მოვლენებზე გამოწერა
event_bus::subscribe("prx.session.created", |event| {
    let payload: SessionCreated = serde_json::from_slice(&event.payload)?;
    log::info!("New session: {}", payload.session_id);
    Ok(())
})?;

// მოვლენის გამოქვეყნება
let payload = serde_json::to_vec(&MyEvent { data: "hello" })?;
event_bus::publish("prx.plugin.my_plugin.my_event", &payload)?;

გამოწერის დეკლარირება დანამატის მანიფესტში

დანამატები გამოწერებს მანიფესტის ფაილში აცხადებენ:

# plugin.toml
[plugin]
name = "my-plugin"
version = "1.0.0"

[permissions]
event_bus_subscribe = [
    "prx.session.*",
    "prx.tool.after_execute",
]
event_bus_publish = [
    "prx.plugin.my_plugin.*",
]

ჰოსტი ამ ნებართვების დეკლარაციებს აღასრულებს. დანამატს არ შეუძლია გამოწერა ან გამოქვეყნება დეკლარირებული ნებართვების გარეთ არსებულ თემებზე.

მიწოდების გარანტიები

მოვლენათა ავტობუსი არა-უმეტეს-ერთხელ მიწოდებას უზრუნველყოფს:

• მოვლენები ყველა შესაბამის გამომწერს ასინქრონულად ეგზავნება
• თუ გამომწერი ნელია ან არ პასუხობს, მოვლენა delivery_timeout_ms-ის შემდეგ იგდება
• თუ შიდა მოვლენათა რიგი სავსეა (channel_capacity მიღწეული), ახალი მოვლენები გაფრთხილებით იგდება
• არ არსებობს პერსისტენციის, ხელახალი ცდის ან დადასტურების მექანიზმი

გარანტირებული მიწოდების მოთხოვნილი სცენარებისთვის განიხილეთ webhook სისტემის ან გარე შეტყობინებების რიგის გამოყენება.

რეკურსიის დაცვა

როდესაც მოვლენის დამმუშავებელი სხვა მოვლენას გამოაქვეყნებს, ჯაჭვი იქმნება. მოვლენათა ავტობუსი რეკურსიის სიღრმეს თვალყურს ადევნებს და max_recursion_depth-ს აღასრულებს:

prx.session.created           <- სიღრმე 0
  -> დამმუშავებელი აქვეყნებს prx.plugin.audit.session_log    <- სიღრმე 1
    -> დამმუშავებელი აქვეყნებს prx.plugin.metrics.counter     <- სიღრმე 2
      -> ...

თუ სიღრმე ლიმიტს გადააჭარბებს, მოვლენა იგდება და გაფრთხილება აღირიცხება:

WARN event_bus: Recursion depth 8 exceeded for topic prx.plugin.metrics.counter, event dropped

ინსტრუმენტის შესრულების ინტერცეპტირება

prx.tool.before_execute მოვლენა ინტერცეპტირებას უჭერს მხარს. გამომწერებს შეუძლიათ ინსტრუმენტის გამოძახების მოდიფიცირება ან გაუქმება გაშვებამდე:

event_bus::subscribe("prx.tool.before_execute", |event| {
    let mut payload: ToolBeforeExecute = serde_json::from_slice(&event.payload)?;

    // საშიში ბრძანებების დაბლოკვა
    if payload.tool_name == "shell" && payload.args.contains("rm -rf") {
        return Err(EventBusError::Rejected("Dangerous command blocked".into()));
    }

    Ok(())
})?;

როდესაც ნებისმიერი გამომწერი შეცდომას დააბრუნებს, ინსტრუმენტის შესრულება უქმდება და შეცდომა აგენტს ეცნობება.

მონიტორინგი

CLI

# ბოლო მოვლენათა ავტობუსის აქტივობის ნახვა
prx events --tail 50

# თემის შაბლონით ფილტრაცია
prx events --topic "prx.session.*"

# მოვლენის დატვირთვების ჩვენება
prx events --verbose

# გამომწერთა რაოდენობის ნახვა
prx events stats

მეტრიკები

მოვლენათა ავტობუსი Prometheus მეტრიკებს გამოაქვეყნებს:

მეტრიკა	ტიპი	აღწერა
prx_event_bus_published_total	Counter	თემის მიხედვით გამოქვეყნებული მოვლენების საერთო რაოდენობა
prx_event_bus_delivered_total	Counter	გამომწერებისთვის მიწოდებული მოვლენების საერთო რაოდენობა
prx_event_bus_dropped_total	Counter	გადაგდებული მოვლენები (რიგი სავსე, ვადაგასვლა, რეკურსია)
prx_event_bus_delivery_duration_seconds	Histogram	მოვლენების გამომწერებისთვის მიწოდების დრო
prx_event_bus_subscribers	Gauge	მიმდინარე გამომწერთა რაოდენობა თემის მიხედვით

შეზღუდვები

• არა-უმეტეს-ერთხელ მიწოდება ნიშნავს, რომ მოვლენები შეიძლება დაიკარგოს, თუ რიგი სავსეა ან გამომწერები ნელია
• მოვლენათა ავტობუსი PRX პროცესის ლოკალურია; მოვლენები კვანძებზე არ ნაწილდება
• დატვირთვის ზომა 64 KB-ით არის შეზღუდული; დიდი მონაცემები ჩადგმის ნაცვლად ID-ით უნდა მიეთითოს
• სიმბოლოანი გამოწერები (განსაკუთრებით prx.**) მნიშვნელოვან დატვირთვას შეიძლება წარმოქმნას; ეკონომიურად გამოიყენეთ
• დანამატის მოვლენათა დამმუშავებლები WASM სენდბოქსში ეშვება და ფაილურ სისტემასა და ქსელს პირდაპირ ვერ წვდება
• მოვლენების თანმიმდევრობა საუკეთესო-მცდელობისაა; მაღალი დატვირთვისას გამომწერებმა მოვლენები არათანმიმდევრობით შეიძლება მიიღონ

დაკავშირებული გვერდები

• დანამატის სისტემის მიმოხილვა
• დანამატის არქიტექტურა -- WASM რანთაიმი და ჰოსტ-სტუმრის საზღვარი
• დეველოპერის სახელმძღვანელო -- დანამატების აწყობა PDK-ით
• ჰოსტ ფუნქციები -- დანამატებისთვის ხელმისაწვდომი ჰოსტ ფუნქციები
• Webhook-ები -- გარე სისტემებისთვის გარანტირებული მიწოდებისთვის