[TRACKING] Major changes for Plugin API 4.0.0

[leogr]

Motivation

Several times, we postponed proposed changes in the Plugin API to avoid breaking changes. The plan is to collect them so that we can release them together once we decide to release the next major API version.

This issue will track these proposed changes and ideas to ensure they are not forgotten.

Proposed API Changes

• Field metadata support: fix(plugin): fix extract offsets handling #2432 (comment)
• ss_plugin_table_fields_vtable https://github.com/falcosecurity/libs/blob/39b018fc3353041efcbbe6adbe7f79cedf91ca83/userspace/plugin/plugin_api.h#L58-L69C3
• ss_plugin_table_reader_vtable https://github.com/falcosecurity/libs/blob/39b018fc3353041efcbbe6adbe7f79cedf91ca83/userspace/plugin/plugin_api.h#L104-L116C3
• ss_plugin_table_writer_vtable https://github.com/falcosecurity/libs/blob/39b018fc3353041efcbbe6adbe7f79cedf91ca83/userspace/plugin/plugin_api.h#L168-L183C3
• extraction capability - reorder the arguments and put ss_plugin_t* as first

  libs/userspace/plugin/plugin_api.h

  Lines 845 to 847 in 39b018f

  	// todo(jasondellaluce): when/if major changes to v4, reorder the arguments
  	// and put ss_plugin_t* as first
  	uint16_t* (*get_extract_event_types)(uint32_t* numtypes, ss_plugin_t* s);

• parsing capability - reorder the arguments and put ss_plugin_t* as first https://github.com/falcosecurity/libs/blob/39b018fc3353041efcbbe6adbe7f79cedf91ca83/userspace/plugin/plugin_api.h#L948C57-L950
• review ss_plugin_state_type and ss_plugin_state_data

  libs/userspace/plugin/plugin_types.h

  Lines 219 to 251 in 39b018f

  	// Types supported by entry fields of state tables.
  	// The noncontinguous numbers are to maintain equality with underlying
  	// falcosecurity libs types.
  	// todo(jasondellaluce): should we merge this with ss_plugin_field_type?
  	typedef enum ss_plugin_state_type {
  	SS_PLUGIN_ST_INT8 = 1,
  	SS_PLUGIN_ST_INT16 = 2,
  	SS_PLUGIN_ST_INT32 = 3,
  	SS_PLUGIN_ST_INT64 = 4,
  	SS_PLUGIN_ST_UINT8 = 5,
  	SS_PLUGIN_ST_UINT16 = 6,
  	SS_PLUGIN_ST_UINT32 = 7,
  	SS_PLUGIN_ST_UINT64 = 8,
  	SS_PLUGIN_ST_STRING = 9,
  	SS_PLUGIN_ST_TABLE = 10,
  	SS_PLUGIN_ST_BOOL = 25
  	} ss_plugin_state_type;
  	// Data representation of entry fields of state tables.
  	// todo(jasondellaluce): should we merge this with what we have for field extraction?
  	typedef union ss_plugin_state_data {
  	int8_t s8;
  	int16_t s16;
  	int32_t s32;
  	int64_t s64;
  	uint8_t u8;
  	uint16_t u16;
  	uint32_t u32;
  	uint64_t u64;
  	const char* str;
  	ss_plugin_bool b;
  	ss_plugin_table_t* table;
  	} ss_plugin_state_data;

Additional context

[leogr]

cc @falcosecurity/libs-maintainers please add those items I surely forgot here. Thank you 🙏