update(sdk): bump plugin_info version (plugin API v2)

This is temporary and required for testing purpose. Another bump should be expected before releasing v0.6.0.

Signed-off-by: Leonardo Grasso <[email protected]>

Author: leogr

Makefile

@@ -14,7 +14,7 @@ SHELL := /bin/bash
 GO    ?= $(shell which go)
 CURL  ?= $(shell which curl)
 
-FALCOSECURITY_LIBS_REVISION ?= 5b9c3ca9ae55800e774e1681a0c5e7d54ca89263
+FALCOSECURITY_LIBS_REVISION ?= 000eb27573af74168510e4836330ff6958c3f355
 FALCOSECURITY_LIBS_REPO ?= falcosecurity/libs
 PLUGINLIB_URL=https://raw.githubusercontent.com/${FALCOSECURITY_LIBS_REPO}/${FALCOSECURITY_LIBS_REVISION}/userspace/plugin
 

pkg/sdk/plugin_api.h

@@ -25,9 +25,9 @@ extern "C" {
 
 
 //
-// API versions of this plugin engine
+// API versions of this plugin framework
 //
-#define PLUGIN_API_VERSION_MAJOR 1
+#define PLUGIN_API_VERSION_MAJOR 2
 #define PLUGIN_API_VERSION_MINOR 0
 #define PLUGIN_API_VERSION_PATCH 0
 
@@ -64,8 +64,9 @@ extern "C" {
 // parameters) if not corresponding to plugin-allocated memory in the
 // cases above. Plugins can safely use the passed memory during the execution
 // of the exported functions.
+
 //
-// Plugins vtable
+// Plugins API vtable
 //
 typedef struct
 {
@@ -74,9 +75,9 @@ typedef struct
 	// Required: yes
 	// Return value: the API version string, in the following format:
 	//       "<major>.<minor>.<patch>", e.g. "1.2.3".
-	// NOTE: to ensure correct interoperability between the engine and the plugins,
+	// NOTE: to ensure correct interoperability between the framework and the plugins,
 	//       we use a semver approach. Plugins are required to specify the version
-	//       of the API they run against, and the engine will take care of checking
+	//       of the API they run against, and the framework will take care of checking
 	//       and enforcing compatibility.
 	//
 	const char *(*get_required_api_version)();
@@ -103,17 +104,20 @@ typedef struct
 	const char *(*get_init_schema)(ss_plugin_schema_type *schema_type);
 
 	//
-	// Initialize the plugin and allocate its non-NULL state.
+	// Initialize the plugin and allocate its state.
 	// Required: yes
 	// Arguments:
 	// - config: a string with the plugin configuration. The format of the
 	//   string is chosen by the plugin itself.
 	// - rc: pointer to a ss_plugin_rc that will contain the initialization result
 	// Return value: pointer to the plugin state that will be treated as opaque
-	//   by the engine and passed to the other plugin functions.
+	//   by the framework and passed to the other plugin functions.
 	//   If rc is SS_PLUGIN_FAILURE, this function may return NULL or a state to
 	//   later retrieve the error string.
-	//
+	// 
+	// If a non-NULL ss_plugin_t* state is returned, then subsequent invocations
+	// of init() must not return the same ss_plugin_t* value again, if not after
+	// it has been disposed with destroy() first.
 	ss_plugin_t *(*init)(const char *config, ss_plugin_rc *rc);
 
 	//
@@ -129,7 +133,7 @@ typedef struct
 	//
 	// In cases where any other api function returns an error, the
 	// plugin should be prepared to return a human-readable error
-	// string with more context for the error. The plugin manager
+	// string with more context for the error. The framework
 	// calls get_last_error() to access that string.
 	//
 	const char *(*get_last_error)(ss_plugin_t *s);
@@ -143,13 +147,13 @@ typedef struct
 
 	//
 	// Return the descriptions of the plugin, which will be printed when displaying
-	// information about the plugin or its events.
+	// information about the plugin.
 	// Required: yes
 	//
 	const char *(*get_description)();
 
 	//
-	// Return a string containing contact info (url, email, twitter, etc) for
+	// Return a string containing contact info (url, email, etc) for
 	// the plugin authors.
 	// Required: yes
 	//
@@ -161,14 +165,15 @@ typedef struct
 	// Return value: a string with a version identifier, in the following format:
 	//        "<major>.<minor>.<patch>", e.g. "1.2.3".
 	// This differs from the api version in that this versions the
-	// plugin itself, as compared to the plugin interface. When
-	// reading capture files, the major version of the plugin that
-	// generated events must match the major version of the plugin
-	// used to read events.
+	// plugin itself. Note, increasing the major version signals breaking
+	// changes in the plugin implementation but must not change the
+	// serialization format of the event data. For example, events written
+	// in pre-existing capture files must always be readable by newer versions
+	// of the plugin.
 	//
 	const char *(*get_version)();
 
-	// Sourcing capabilities related
+	// Event sourcing capability API
 	struct
 	{
 		//
@@ -180,33 +185,38 @@ typedef struct
 		uint32_t (*get_id)();
 
 		//
-		// Return a string describing the events generated by this plugin with event sourcing capabilities.
+		// Return a string representing the name of the event source generated
+		// by this plugin.
 		// Required: yes
-		// Example event sources would be strings like "syscall",
-		// "k8s_audit", etc. The source can be used by extractor
-		// plugins to filter the events they receive.
+		// Example event sources would be strings like "aws_cloudtrail",
+		// "k8s_audit", etc. The source can be used by plugins with event
+		// sourcing capabilities to filter the events they receive.
 		//
 		const char* (*get_event_source)();
 
 		//
-		// Open the source and start a capture (e.g. stream of events)
+		// Open the event source and start a capture (e.g. stream of events)
 		// Required: yes
 		// Arguments:
 		// - s: the plugin state returned by init()
-		// - params: the open parameters, as a string. The format is defined by the plugin
-		//   itsef
+		// - params: the open parameters, as an opaque string.
+		//           The string format is defined by the plugin itself
 		// - rc: pointer to a ss_plugin_rc that will contain the open result
-		// Return value: a pointer to the open context that will be passed to next_batch(),
-		//   close(), event_to_string() and extract_fields.
+		// Return value: a pointer to the opened plugin instance that will be
+		//               passed to next_batch(), close(), event_to_string()
+		//               and extract_fields().
 		//
+		// If a non-NULL ss_instance_t* instance is returned, then subsequent
+		// invocations of open() must not return the same ss_instance_t* value
+		// again, if not after it has been disposed with close() first.
 		ss_instance_t* (*open)(ss_plugin_t* s, const char* params, ss_plugin_rc* rc);
 
 		//
 		// Close a capture.
 		// Required: yes
 		// Arguments:
-		// - s: the plugin context, returned by init(). Can be NULL.
-		// - h: the capture context, returned by open(). Can be NULL.
+		// - s: the plugin state, returned by init(). Can be NULL.
+		// - h: the plugin instance, returned by open(). Can be NULL.
 		//
 		void (*close)(ss_plugin_t* s, ss_instance_t* h);
 
@@ -215,14 +225,21 @@ typedef struct
 		// Any of the values in the returned list are valid parameters for open().
 		// Required: no
 		// Return value: a string with the list of open params encoded as
-		//   a json array.
-		//   Each field entry is a json object with the following properties:
-		//     "value": a string usable as an open() parameter.
-		//     "desc": (optional) a string with a description of the parameter.
+		//   a json array. Each field entry is a json object with the following
+		//   properties:
+		//     - "value": a string usable as an open() parameter.
+		//     - "desc": (optional) a string with a description of the parameter.
+		//     - "separator": (optional) a separator string, for when "value"
+		//                    represents multiple contatenated open parameters
 		//   Example return value:
 		//   [
 		//      {"value": "resource1", "desc": "An example of openable resource"},
-		//      {"value": "resource2", "desc": "Another example of openable resource"}
+		//      {"value": "resource2", "desc": "Another example of openable resource"},
+		//      {
+		//          "value": "res1;res2;res3",
+		//          "desc": "Some names",
+		//          "separator": ";"
+		//      }
 		//   ]
 		const char* (*list_open_params)(ss_plugin_t* s, ss_plugin_rc* rc);
 
@@ -231,7 +248,7 @@ typedef struct
 		// Required: no
 		// Arguments:
 		// - progress_pct: the read progress, as a number between 0 (no data has been read)
-		//   and 10000 (100% of the data has been read). This encoding allows the engine to
+		//   and 10000 (100% of the data has been read). This encoding allows the framework to
 		//   print progress decimals without requiring to deal with floating point numbers
 		//   (which could cause incompatibility problems with some languages).
 		// Return value: a string representation of the read
@@ -245,6 +262,11 @@ typedef struct
 		//       when possible, it's recommended as it provides valuable information to the
 		//       user.
 		//
+		// This function can be invoked concurrently by multiple threads,
+		// each with distinct and unique parameter values.
+		// If the returned pointer is non-NULL, then it must be uniquely
+		// attached to the ss_instance_t* parameter value. The pointer must not
+		// be shared across multiple distinct ss_instance_t* values.
 		const char* (*get_progress)(ss_plugin_t* s, ss_instance_t* h, uint32_t* progress_pct);
 
 		//
@@ -261,6 +283,11 @@ typedef struct
 		//   and must not be deallocated or modified until the next call to
 		//   event_to_string().
 		//
+		// This function can be invoked concurrently by multiple threads,
+		// each with distinct and unique parameter values.
+		// If the returned pointer is non-NULL, then it must be uniquely
+		// attached to the ss_plugin_t* parameter value. The pointer must not
+		// be shared across multiple distinct ss_plugin_t* values.
 		const char* (*event_to_string)(ss_plugin_t *s, const ss_plugin_event *evt);
 
 		//
@@ -275,10 +302,15 @@ typedef struct
 		//     next_batch() or close().
 		// Required: yes
 		//
+		// This function can be invoked concurrently by multiple threads,
+		// each with distinct and unique parameter values.
+		// The value of the ss_plugin_event** output parameter must be uniquely
+		// attached to the ss_instance_t* parameter value. The pointer must not
+		// be shared across multiple distinct ss_instance_t* values.
 		ss_plugin_rc (*next_batch)(ss_plugin_t* s, ss_instance_t* h, uint32_t *nevts, ss_plugin_event **evts);
 	};
 
-	// Extraction capability related
+	// Field extraction capability API
 	struct
 	{
 		//
@@ -305,9 +337,6 @@ typedef struct
 		//     "type": one of "string", "uint64"
 		//     "isList: (optional) If present and set to true, notes
 		//              that the field extracts a list of values.
-		//     "argRequired": [DEPRECATED, use "arg" property instead]
-		//                   (optional) If present and set to true, notes
-		//                   that the field requires an argument e.g. field[arg].
 		//     "arg": (optional) if present, notes that the field can accept
 		//             an argument e.g. field[arg]. More precisely, the following
 		//             flags could be specified:
@@ -325,9 +354,8 @@ typedef struct
 		//     "desc": a string with a description of the field
 		// Example return value:
 		// [
-		//    {"type": "string", "name": "field1", "argRequired": true, "desc": "Describing field 1"}, [DEPRECATED 'argRequired' property]
-		//    {"type": "uint64", "name": "field2", "desc": "Describing field 2"},
-		//    {"type": "string", "name": "field3", "arg": {"isRequired": true, "isIndex": true,}, "desc": "Describing field 3"},
+		//    {"type": "uint64", "name": "field1", "desc": "Describing field 1"},
+		//    {"type": "string", "name": "field2", "arg": {"isRequired": true, "isIndex": true}, "desc": "Describing field 2"},
 		// ]
 		const char* (*get_fields)();
 
@@ -348,6 +376,11 @@ typedef struct
 		//
 		// Return value: A ss_plugin_rc with values SS_PLUGIN_SUCCESS or SS_PLUGIN_FAILURE.
 		//
+		// This function can be invoked concurrently by multiple threads,
+		// each with distinct and unique parameter values.
+		// The value of the ss_plugin_extract_field* output parameter must be
+		// uniquely attached to the ss_plugin_t* parameter value. The pointer
+		// must not be shared across multiple distinct ss_plugin_t* values.
 		ss_plugin_rc (*extract_fields)(ss_plugin_t *s, const ss_plugin_event *evt, uint32_t num_fields, ss_plugin_extract_field *fields);
 	};
 } plugin_api;