Skip to content

Commit 20c3c5b

Browse files
committed
feat(event): opt-in dual-sink for native queue and event plugin
Allow the native ZMQ queue and the event plugin to run at the same time, with activation made explicit rather than inferred from a path so that existing native-queue deployments keep their current behavior after an upgrade. - Plugin activation is resolved explicitly in Args via EventPluginConfig.resolveUseEventPlugin(): with the native queue on it only joins when the operator opts in (runPluginWithNativeQueue = true), so a stale "path" in an upgraded config can never silently load a plugin. - Add pluginLoadFailurePolicy ("fail" | "ignore") to define behavior when the plugin cannot load; default "fail" preserves data integrity. - Isolate plugin trigger posting in try/catch so a plugin fault cannot tear down the node event thread; serialize each trigger once and share it with both sinks so the default path keeps its current cost. - Apply plugin back-pressure (isBusy) whenever the plugin is active, including dual-sink mode, in EventPluginLoader and HistoryEventService. - Tests: upgrade regression, dual-sink routing, plugin-failure isolation, load-failure policy, and updated back-pressure semantics.
1 parent 381d369 commit 20c3c5b

8 files changed

Lines changed: 292 additions & 73 deletions

File tree

‎common/src/main/java/org/tron/common/logsfilter/EventPluginConfig.java‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,18 @@ public class EventPluginConfig {
3939
@Setter
4040
private boolean useNativeQueue;
4141

42+
// Whether the event plugin should be activated. Resolved in Args from the plugin path
43+
// and the runPluginWithNativeQueue opt-in, so the loader never has to infer activation
44+
// from a possibly-stale path on its own.
45+
@Getter
46+
@Setter
47+
private boolean useEventPlugin;
48+
49+
// See EventConfig#pluginLoadFailurePolicy ("fail" | "ignore").
50+
@Getter
51+
@Setter
52+
private String pluginLoadFailurePolicy = "fail";
53+
4254
@Getter
4355
@Setter
4456
private int bindPort;
@@ -52,6 +64,24 @@ public class EventPluginConfig {
5264
@Setter
5365
private List<TriggerConfig> triggerConfigList;
5466

67+
/**
68+
* Decide whether the event plugin should be an active sink.
69+
*
70+
* <p>Backward-compatible by design:
71+
* <ul>
72+
* <li>native queue OFF: the plugin is the only sink, so it is active whenever a
73+
* plugin path is configured (unchanged legacy behavior);</li>
74+
* <li>native queue ON: the plugin runs alongside the queue only when the operator
75+
* opts in via {@code runPluginWithNativeQueue}. A leftover path alone never
76+
* activates it, so upgrading a native-queue node cannot suddenly load a plugin.
77+
* </li>
78+
* </ul>
79+
*/
80+
public static boolean resolveUseEventPlugin(boolean hasPluginPath, boolean useNativeQueue,
81+
boolean runPluginWithNativeQueue) {
82+
return hasPluginPath && (!useNativeQueue || runPluginWithNativeQueue);
83+
}
84+
5585
public EventPluginConfig() {
5686
pluginPath = "";
5787
serverAddress = "";

‎common/src/main/java/org/tron/core/config/args/EventConfig.java‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,15 @@ public class EventConfig {
2525
private String server = "";
2626
private String dbconfig = "";
2727
private boolean contractParse = true;
28+
// When the native queue is enabled, the event plugin is only activated in addition
29+
// to it when this flag is explicitly set to true. This keeps existing native-queue
30+
// deployments (which may still carry a stale "path") on native-only behavior after
31+
// an upgrade. Ignored when useNativeQueue = false (plugin is the only sink then).
32+
private boolean runPluginWithNativeQueue = false;
33+
// What to do when the event plugin fails to load:
34+
// "fail" - abort node startup (default, avoids silently losing plugin data)
35+
// "ignore" - log the error and keep running with the native queue only
36+
private String pluginLoadFailurePolicy = "fail";
2837
@Getter(lombok.AccessLevel.NONE)
2938
@Setter(lombok.AccessLevel.NONE)
3039
private NativeConfig nativeQueue = new NativeConfig();

‎common/src/main/resources/reference.conf‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -769,6 +769,8 @@ event.subscribe = {
769769
server = ""
770770
dbconfig = ""
771771
contractParse = true
772+
runPluginWithNativeQueue = false
773+
pluginLoadFailurePolicy = "fail"
772774

773775
topics = [
774776
{

‎framework/src/main/java/org/tron/common/logsfilter/EventPluginLoader.java‎

Lines changed: 100 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
import java.util.List;
99
import java.util.Objects;
1010
import java.util.Set;
11+
import java.util.function.Consumer;
1112
import java.util.stream.Collectors;
1213
import lombok.Getter;
1314
import lombok.extern.slf4j.Slf4j;
@@ -78,6 +79,15 @@ public class EventPluginLoader {
7879
@Getter
7980
private boolean useNativeQueue = false;
8081

82+
// Whether the event plugin is an active sink. May be turned off at runtime if the
83+
// plugin fails to load under the "ignore" failure policy.
84+
@Getter
85+
private boolean useEventPlugin = false;
86+
87+
private static final String FAIL_POLICY = "fail";
88+
89+
private String pluginLoadFailurePolicy = FAIL_POLICY;
90+
8191
public static EventPluginLoader getInstance() {
8292
if (Objects.isNull(instance)) {
8393
synchronized (EventPluginLoader.class) {
@@ -234,12 +244,37 @@ public boolean start(EventPluginConfig config) {
234244
this.triggerConfigList = config.getTriggerConfigList();
235245

236246
useNativeQueue = config.isUseNativeQueue();
247+
useEventPlugin = config.isUseEventPlugin();
248+
if (StringUtils.hasText(config.getPluginLoadFailurePolicy())) {
249+
pluginLoadFailurePolicy = config.getPluginLoadFailurePolicy().trim();
250+
}
251+
252+
if (!useNativeQueue && !useEventPlugin) {
253+
logger.error("No event sink is configured: enable the native queue "
254+
+ "or set a plugin path.");
255+
return false;
256+
}
257+
258+
// Start the plugin first so that, under the "fail" policy, a plugin problem is
259+
// surfaced before the native queue starts accepting subscribers.
260+
if (useEventPlugin && !launchEventPlugin(config)) {
261+
if (FAIL_POLICY.equalsIgnoreCase(pluginLoadFailurePolicy)) {
262+
return false;
263+
}
264+
// "ignore" policy: fall back to native-queue-only operation.
265+
logger.warn("Event plugin failed to load; continuing without it "
266+
+ "(pluginLoadFailurePolicy = ignore).");
267+
useEventPlugin = false;
268+
if (!useNativeQueue) {
269+
return false;
270+
}
271+
}
237272

238-
if (config.isUseNativeQueue()) {
273+
if (useNativeQueue) {
239274
return launchNativeQueue(config);
240275
}
241276

242-
return launchEventPlugin(config);
277+
return true;
243278
}
244279

245280
private void setPluginConfig() {
@@ -271,7 +306,7 @@ private void setSingleTriggerConfig(TriggerConfig triggerConfig) {
271306
blockLogTriggerSolidified = false;
272307
}
273308

274-
if (!useNativeQueue) {
309+
if (useEventPlugin) {
275310
setPluginTopic(Trigger.BLOCK_TRIGGER, triggerConfig.getTopic());
276311
}
277312

@@ -291,7 +326,7 @@ private void setSingleTriggerConfig(TriggerConfig triggerConfig) {
291326
transactionLogTriggerSolidified = false;
292327
}
293328

294-
if (!useNativeQueue) {
329+
if (useEventPlugin) {
295330
setPluginTopic(Trigger.TRANSACTION_TRIGGER, triggerConfig.getTopic());
296331
}
297332

@@ -303,7 +338,7 @@ private void setSingleTriggerConfig(TriggerConfig triggerConfig) {
303338
contractEventTriggerEnable = false;
304339
}
305340

306-
if (!useNativeQueue) {
341+
if (useEventPlugin) {
307342
setPluginTopic(Trigger.CONTRACTEVENT_TRIGGER, triggerConfig.getTopic());
308343
}
309344

@@ -319,7 +354,7 @@ private void setSingleTriggerConfig(TriggerConfig triggerConfig) {
319354
contractLogTriggerRedundancy = false;
320355
}
321356

322-
if (!useNativeQueue) {
357+
if (useEventPlugin) {
323358
setPluginTopic(Trigger.CONTRACTLOG_TRIGGER, triggerConfig.getTopic());
324359
}
325360
} else if (EventPluginConfig.SOLIDITY_TRIGGER_NAME
@@ -329,7 +364,7 @@ private void setSingleTriggerConfig(TriggerConfig triggerConfig) {
329364
} else {
330365
solidityTriggerEnable = false;
331366
}
332-
if (!useNativeQueue) {
367+
if (useEventPlugin) {
333368
setPluginTopic(Trigger.SOLIDITY_TRIGGER, triggerConfig.getTopic());
334369
}
335370
} else if (EventPluginConfig.SOLIDITY_EVENT_NAME
@@ -340,7 +375,7 @@ private void setSingleTriggerConfig(TriggerConfig triggerConfig) {
340375
solidityEventTriggerEnable = false;
341376
}
342377

343-
if (!useNativeQueue) {
378+
if (useEventPlugin) {
344379
setPluginTopic(Trigger.SOLIDITY_EVENT_TRIGGER, triggerConfig.getTopic());
345380
}
346381
} else if (EventPluginConfig.SOLIDITY_LOG_NAME
@@ -354,19 +389,33 @@ private void setSingleTriggerConfig(TriggerConfig triggerConfig) {
354389
solidityLogTriggerEnable = false;
355390
solidityLogTriggerRedundancy = false;
356391
}
357-
if (!useNativeQueue) {
392+
if (useEventPlugin) {
358393
setPluginTopic(Trigger.SOLIDITY_LOG_TRIGGER, triggerConfig.getTopic());
359394
}
360395
}
361396
}
362397

398+
// Route a trigger to the plugin listeners, keeping a plugin fault from tearing down
399+
// the node's event thread. Serialization is done once by the caller and shared with
400+
// the native queue, so dual-sink mode adds no extra serialization on the hot path.
401+
private void postToPlugin(Consumer<IPluginEventListener> handler) {
402+
if (Objects.isNull(eventListeners)) {
403+
return;
404+
}
405+
try {
406+
eventListeners.forEach(handler);
407+
} catch (Exception e) {
408+
logger.error("event plugin failed to handle trigger", e);
409+
}
410+
}
411+
363412
public void postSolidityTrigger(SolidityTrigger trigger) {
413+
String json = toJsonString(trigger);
364414
if (useNativeQueue) {
365-
NativeMessageQueue.getInstance()
366-
.publishTrigger(toJsonString(trigger), trigger.getTriggerName());
367-
} else {
368-
eventListeners.forEach(listener ->
369-
listener.handleSolidityTrigger(toJsonString(trigger)));
415+
NativeMessageQueue.getInstance().publishTrigger(json, trigger.getTriggerName());
416+
}
417+
if (useEventPlugin) {
418+
postToPlugin(listener -> listener.handleSolidityTrigger(json));
370419
}
371420
}
372421

@@ -427,6 +476,9 @@ public synchronized boolean isContractLogTriggerRedundancy() {
427476
}
428477

429478
private void setPluginTopic(int eventType, String topic) {
479+
if (Objects.isNull(eventListeners)) {
480+
return;
481+
}
430482
eventListeners.forEach(listener -> listener.setTopic(eventType, topic));
431483
}
432484

@@ -482,66 +534,70 @@ public void stopPlugin() {
482534
}
483535

484536
public void postBlockTrigger(BlockLogTrigger trigger) {
537+
String json = toJsonString(trigger);
485538
if (useNativeQueue) {
486-
NativeMessageQueue.getInstance()
487-
.publishTrigger(toJsonString(trigger), trigger.getTriggerName());
488-
} else {
489-
eventListeners.forEach(listener ->
490-
listener.handleBlockEvent(toJsonString(trigger)));
539+
NativeMessageQueue.getInstance().publishTrigger(json, trigger.getTriggerName());
540+
}
541+
if (useEventPlugin) {
542+
postToPlugin(listener -> listener.handleBlockEvent(json));
491543
}
492544
}
493545

494546
public void postSolidityLogTrigger(ContractLogTrigger trigger) {
547+
String json = toJsonString(trigger);
495548
if (useNativeQueue) {
496-
NativeMessageQueue.getInstance()
497-
.publishTrigger(toJsonString(trigger), trigger.getTriggerName());
498-
} else {
499-
eventListeners.forEach(listener ->
500-
listener.handleSolidityLogTrigger(toJsonString(trigger)));
549+
NativeMessageQueue.getInstance().publishTrigger(json, trigger.getTriggerName());
550+
}
551+
if (useEventPlugin) {
552+
postToPlugin(listener -> listener.handleSolidityLogTrigger(json));
501553
}
502554
}
503555

504556
public void postSolidityEventTrigger(ContractEventTrigger trigger) {
557+
String json = toJsonString(trigger);
505558
if (useNativeQueue) {
506-
NativeMessageQueue.getInstance()
507-
.publishTrigger(toJsonString(trigger), trigger.getTriggerName());
508-
} else {
509-
eventListeners.forEach(listener ->
510-
listener.handleSolidityEventTrigger(toJsonString(trigger)));
559+
NativeMessageQueue.getInstance().publishTrigger(json, trigger.getTriggerName());
560+
}
561+
if (useEventPlugin) {
562+
postToPlugin(listener -> listener.handleSolidityEventTrigger(json));
511563
}
512564
}
513565

514566
public void postTransactionTrigger(TransactionLogTrigger trigger) {
567+
String json = toJsonString(trigger);
515568
if (useNativeQueue) {
516-
NativeMessageQueue.getInstance()
517-
.publishTrigger(toJsonString(trigger), trigger.getTriggerName());
518-
} else {
519-
eventListeners.forEach(listener -> listener.handleTransactionTrigger(toJsonString(trigger)));
569+
NativeMessageQueue.getInstance().publishTrigger(json, trigger.getTriggerName());
570+
}
571+
if (useEventPlugin) {
572+
postToPlugin(listener -> listener.handleTransactionTrigger(json));
520573
}
521574
}
522575

523576
public void postContractLogTrigger(ContractLogTrigger trigger) {
577+
String json = toJsonString(trigger);
524578
if (useNativeQueue) {
525-
NativeMessageQueue.getInstance()
526-
.publishTrigger(toJsonString(trigger), trigger.getTriggerName());
527-
} else {
528-
eventListeners.forEach(listener ->
529-
listener.handleContractLogTrigger(toJsonString(trigger)));
579+
NativeMessageQueue.getInstance().publishTrigger(json, trigger.getTriggerName());
580+
}
581+
if (useEventPlugin) {
582+
postToPlugin(listener -> listener.handleContractLogTrigger(json));
530583
}
531584
}
532585

533586
public void postContractEventTrigger(ContractEventTrigger trigger) {
587+
String json = toJsonString(trigger);
534588
if (useNativeQueue) {
535-
NativeMessageQueue.getInstance()
536-
.publishTrigger(toJsonString(trigger), trigger.getTriggerName());
537-
} else {
538-
eventListeners.forEach(listener ->
539-
listener.handleContractEventTrigger(toJsonString(trigger)));
589+
NativeMessageQueue.getInstance().publishTrigger(json, trigger.getTriggerName());
590+
}
591+
if (useEventPlugin) {
592+
postToPlugin(listener -> listener.handleContractEventTrigger(json));
540593
}
541594
}
542595

543596
public boolean isBusy() {
544-
if (useNativeQueue) {
597+
// Back-pressure guards the plugin's async pending queue, so it applies whenever the
598+
// plugin is an active sink — including dual-sink mode. The native queue has no such
599+
// queue of its own and never reports busy.
600+
if (!useEventPlugin) {
545601
return false;
546602
}
547603
int queueSize = 0;

‎framework/src/main/java/org/tron/core/config/args/Args.java‎

Lines changed: 23 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -372,17 +372,29 @@ private static void applyEventConfig(EventConfig ec) {
372372
epc.setBindPort(nq.getBindport());
373373
epc.setSendQueueLength(nq.getSendqueuelength());
374374

375-
if (!nq.isUseNativeQueue()) {
376-
if (StringUtils.isNotEmpty(ec.getPath())) {
377-
epc.setPluginPath(ec.getPath().trim());
378-
}
379-
if (StringUtils.isNotEmpty(ec.getServer())) {
380-
epc.setServerAddress(ec.getServer().trim());
381-
}
382-
if (StringUtils.isNotEmpty(ec.getDbconfig())) {
383-
epc.setDbConfig(ec.getDbconfig().trim());
384-
}
385-
}
375+
// Plugin connection settings are always copied when a path is configured, so the
376+
// plugin can run either on its own (native queue off) or alongside the native queue.
377+
boolean hasPluginPath = StringUtils.isNotEmpty(ec.getPath());
378+
if (hasPluginPath) {
379+
epc.setPluginPath(ec.getPath().trim());
380+
}
381+
if (StringUtils.isNotEmpty(ec.getServer())) {
382+
epc.setServerAddress(ec.getServer().trim());
383+
}
384+
if (StringUtils.isNotEmpty(ec.getDbconfig())) {
385+
epc.setDbConfig(ec.getDbconfig().trim());
386+
}
387+
388+
// Resolve plugin activation explicitly (never inferred later from the raw path):
389+
// - native queue OFF: the plugin is the only sink, so activate it whenever a path
390+
// is set (unchanged legacy behavior).
391+
// - native queue ON : the plugin runs alongside the queue ONLY when the operator
392+
// opts in via runPluginWithNativeQueue. A leftover "path" alone never activates
393+
// it, so upgrading a native-queue node cannot suddenly start loading a plugin.
394+
boolean useEventPlugin = EventPluginConfig.resolveUseEventPlugin(
395+
hasPluginPath, nq.isUseNativeQueue(), ec.isRunPluginWithNativeQueue());
396+
epc.setUseEventPlugin(useEventPlugin);
397+
epc.setPluginLoadFailurePolicy(ec.getPluginLoadFailurePolicy());
386398

387399
// topics
388400
List<TriggerConfig> triggerConfigs = new ArrayList<>();

‎framework/src/main/java/org/tron/core/services/event/HistoryEventService.java‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -67,11 +67,13 @@ private void syncEvent() {
6767
if (thread.isInterrupted() || isClosed) {
6868
throw new InterruptedException();
6969
}
70-
if (instance.isUseNativeQueue()) {
71-
Thread.sleep(20);
72-
} else if (instance.isBusy()) {
70+
// Respect the plugin's back-pressure first so it holds even in dual-sink mode
71+
// (native queue + plugin), then apply the native queue's own pacing throttle.
72+
if (instance.isBusy()) {
7373
Thread.sleep(100);
7474
continue;
75+
} else if (instance.isUseNativeQueue()) {
76+
Thread.sleep(20);
7577
}
7678
BlockEvent blockEvent = blockEventGet.getBlockEvent(tmp);
7779
realtimeEventService.flush(blockEvent, false);

0 commit comments

Comments
 (0)