trigger_plugin_interface.h File Reference

Plugin contract for reacting to trigger-recorder events – above all, deciding what happens to a dumped bag after it is written (network upload, archival, notification, cleanup). More...

#include <cstdint>
#include <string>
#include "../base/plugin.h"
#include "../impl/types.h"

Include dependency graph for trigger_plugin_interface.h:

Go to the source code of this file.

Classes
class	vlink::TriggerPluginInterface
	Abstract plugin base notified across a TriggerRecorder's life cycle and dump pipeline. More...
struct	vlink::TriggerPluginInterface::TriggerContext
	Describes an accepted trigger request, delivered to on_trigger(). More...
struct	vlink::TriggerPluginInterface::DumpContext
	Describes the dump currently being written, delivered to on_dump_started() / on_frame(). More...
struct	vlink::TriggerPluginInterface::DumpResult
	Final outcome of a dump, delivered to on_dump_finished() / on_dump_failed(). More...

Namespaces
	vlink

Detailed Description

Plugin contract for reacting to trigger-recorder events – above all, deciding what happens to a dumped bag after it is written (network upload, archival, notification, cleanup).

TriggerPluginInterface is a dynamic plugin loaded through the VLink Plugin framework and attached to a TriggerRecorder via TriggerRecorder::bind_trigger_interface(). Unlike BagPluginInterface – a frame-forwarding pipeline that rewrites traffic in flight – this interface is an observer over the recorder's life cycle: the recorder owns the ring buffer and the disk write, and the plugin is notified at each stage so it can drive the next step. The primary lifecycle hook is on_dump_finished(), invoked once the bag file is fully written and closed – the natural place to upload the file to a backend, move it to long-term storage, enqueue it for transfer, or fire an alert.

A broad set of hooks is provided so an implementation can instrument the whole flow. Implementations supply init() and on_dump_finished(); the remaining hooks have default no-op implementations.

Plugin contract:

Hook	Stage / thread	Purpose
init()	plugin load (daemon thread)	Parse the host-supplied configuration
on_start()	engine start (recorder loop)	Acquire resources (open an upload session)
on_stop()	engine stop (recorder loop)	Release resources
on_trigger()	window captured (recorder loop)	A dump is about to run for this request
on_dump_started()	writer opened (recorder loop)	The output file is being written
on_frame()	frame submitted (recorder loop)	Inspect / count each writer-accepted frame
on_dump_finished()	file closed (recorder loop)	Upload / archive / notify – the next step
on_dump_failed()	dump aborted (recorder loop)	React to a failed dump
on_file_rotated()	file removed (recorder loop)	A rotated-out file was deleted
flush()	before unbind / teardown	Drain plugin-internal async work

Note

Dump hooks and normal recorder start/stop hooks run on the recorder loop. Bind the plugin while the recorder is stopped. A slow hook blocks later recorder work, so offload it to a plugin-owned worker and drain it in flush(). on_frame() can be hot – keep it cheap.

Hooks must not re-enter the owning recorder.

Example (upload every dumped bag to a backend)

class UploadPlugin : public vlink::TriggerPluginInterface {
 public:
  bool init(const std::string& config) override { return queue_.configure(config); }
 
  void on_dump_finished(const DumpResult& result) override {
    if (result.success) {
      queue_.push(result.path);  // hand off to a background uploader; drain it in flush()
    }
  }
 
  void flush() override { queue_.drain(); }
 
 private:
  UploadQueue queue_;
};
VLINK_PLUGIN_DECLARE(UploadPlugin, 2, 0)