Version: 3.11.2

Module rspamd_task

Module `rspamd_task`

This module provides routines for tasks manipulation in rspamd. Tasks usually represent messages being scanned, and this API provides access to such elements as headers, symbols, metrics and so on and so forth. Normally, task objects are passed to the lua callbacks allowing to check specific properties of messages and add the corresponding symbols to the scan's results.

Example:

rspamd_config.DATE_IN_PAST = function(task)
	local dm = task:get_date{format = 'message', gmt = true}
	local dt = task:get_date{format = 'connect', gmt = true}
	-- A day
	if dt - dm > 86400 then
		return true
	end

	return false
end

Brief content:

Functions:

Function	Description
`rspamd_task.create([cfg])`	Create a new empty task.
`rspamd_task.load_from_file(filename[, cfg])`	Loads a message from specific file.
`rspamd_task.load_from_string(message[, cfg])`	Loads a message from specific file.

Methods:

Method	Description
`task:get_message()`	Returns task raw message content as opaque text.
`task:set_message(msg)`	Updates task message with another message; It also parses a message to.
`task:process_message()`	Parses message.
`task:get_cfg()`	Get configuration object for a task.
`task:get_mempool()`	Returns memory pool valid for a lifetime of task.
`task:get_session()`	Returns asynchronous session object that is used by many rspamd asynchronous.
`task:set_session(session)`	Sets new async session for a task.
`task:get_ev_base()`	Return asynchronous event base for using in callbacks and resolver.
`task:get_worker()`	Returns a worker object associated with the task.
`task:insert_result([enforce_symbol,]symbol, weight[, option1, ...])`	Insert specific symbol to the tasks scanning results assigning the initial.
`task:insert_result_named(shadow_result, [enforce_symbol,]symbol, weight[, option1, ...])`	Insert specific symbol to the tasks scanning results assigning the initial.
`task:adjust_result(symbol, score[, option1, ...])`	Alters the existing symbol's score to a new score.
`task:remove_result(symbol[, shadow_result])`	Removes the symbol from a named or unnamed/default result.
`task:set_pre_result(action, [message, [module], [score], [priority], [flags])`	Sets pre-result for a task.
`task:has_pre_result()`	Returns true if task has some pre-result being set.
`task:append_message(message, [category])`	Adds a message to scanning output.
[`task:get_urls([need_emails	list_protos][, need_images])`](#m1860f)
`task:get_urls_filtered([{flags_include}, [{flags_exclude}]], [{protocols_mask}])`	Get urls managed by either exclude or include flags list.
`task:has_urls([need_emails])`	Returns 'true' if a task has urls listed.
`task:inject_url(url)`	Inserts an url into a task (useful for redirected urls).
`task:get_content()`	Get raw content for the specified task.
`task:get_filename()`	Returns filename for a specific task.
`task:get_rawbody()`	Get raw body for the specified task.
`task:get_emails()`	Get all email addresses found in a message.
`task:get_text_parts()`	Get all text (and HTML) parts found in a message.
`task:get_parts()`	Get all mime parts found in a message.
`task:get_meta_words([how='stem'])`	Get meta words from task (subject and displayed names).
`task:get_request_header(name)`	Get value of a HTTP request header.
`task:set_request_header(name, value)`	Set value of a HTTP request header.
`task:get_subject()`	Returns task subject (either from the protocol override or from a header).
`task:get_header(name[, case_sensitive])`	Get decoded value of a header specified with optional case_sensitive flag.
`task:has_header(name[, case_sensitive])`	Get decoded value of a header specified with optional case_sensitive flag.
`task:get_header_raw(name[, case_sensitive])`	Get raw value of a header specified with optional case_sensitive flag.
`task:get_header_full(name[, case_sensitive[, need_modified]])`	Get raw value of a header specified with optional case_sensitive flag.
`task:get_header_count(name[, case_sensitive])`	Lightweight version if you need just a header's count.
`task:get_raw_headers()`	Get all undecoded headers of a message as a string.
`task:get_headers([need_modified=false])`	Get all headers of a message in the same format as get_header_full.
`task:modify_header(name, mods)`	Modify an existing or non-existing header with the name `name`.
`task:get_received_headers()`	Returns a list of tables of parsed received headers.
`task:get_queue_id()`	Returns queue ID of the message being processed.
`task:get_uid()`	Returns ID of the task being processed.
`task:get_resolver()`	Returns ready to use rspamd_resolver object suitable for making asynchronous DNS requests.
`task:set_resolver(resolver)`	Sets rspamd_resolver for a specified task.
`task:inc_dns_req()`	Increment number of DNS requests for the task.
`task:get_dns_req()`	Get number of dns requests being sent in the task.
`task:has_recipients([type])`	Return true if there are SMTP or MIME recipients for a task.
`task:get_recipients([type])`	Return SMTP or MIME recipients for a task.
`task:get_principal_recipient()`	Returns a single string with so called `principal recipient` for a message.
`task:get_reply_sender()`	Returns a single string with address that should be used to reply on a message.
`task:set_recipients([type], {rcpt1, rcpt2...}, [how='add'])`	Sets recipients for a task.
`task:has_from([type])`	Return true if there is SMTP or MIME sender for a task.
`task:get_from([type])`	Return SMTP or MIME sender for a task.
`task:set_from(type, addr)`	Sets sender for a task.
`task:get_user()`	Returns authenticated user name for this task if specified by an MTA.
`task:set_user([username])`	Sets or resets (if username is not specified) authenticated user name for this task.
`task:get_from_ip()`	Returns rspamd_ip object of a sender that is provided by MTA.
`task:set_from_ip(str)`	Set tasks's IP address based on the passed string.
`task:get_client_ip()`	Returns rspamd_ip object of a client connected to rspamd (normally, it is an IP address of MTA).
`task:get_helo()`	Returns the value of SMTP helo provided by MTA.
`task:get_hostname()`	Returns the value of sender's hostname provided by MTA.
`task:get_images()`	Returns list of all images found in a task as a table of `rspamd_image`.
`task:get_archives()`	Returns list of all archives found in a task as a table of `rspamd_archive`.
`task:get_dkim_results()`	Returns list of all dkim check results as table of maps.
`task:get_symbol(name, [shadow_result_name])`	Searches for a symbol `name` in all metrics results and returns a list of tables.
`task:get_symbols_all()`	Returns array of symbols matched in default metric with all metadata.
`task:get_symbols([shadow_result_name])`	Returns array of all symbols matched for this task.
`task:get_groups([need_private])`	Returns a map [group -> group_score] for matched group.
`task:get_symbols_numeric()`	Returns array of all symbols matched for this task.
`task:get_symbols_tokens()`	Returns array of all symbols as statistical tokens.
`task:process_ann_tokens(symbols, ann_tokens, offset, [min])`	Processes ann tokens.
`task:has_symbol(name, [shadow_result_name])`	Fast path to check if a specified symbol is in the task's results.
`task:enable_symbol(name)`	Enable specified symbol for this particular task.
`task:disable_symbol(name)`	Disable specified symbol for this particular task.
`task:get_date(type[, gmt])`	Returns timestamp for a connection or for a MIME message.
`task:get_message_id()`	Returns message identifier from the `Message-ID` header.
`task:get_timeval([raw])`	Returns the timestamp for a task start processing time.
`task:get_scan_time([set])`	Returns 2 floating point numbers.
`task:get_metric_result()`	Get full result of a metric as a table.
`task:get_metric_score(name)`	Get the current score of metric `name` (must be nil or 'default') .
`task:get_metric_threshold(action)`	Get the current threshold of the action `action` for the default metric.
`task:get_metric_action(name)`	Get the current action of metric `name` (must be nil or 'default').
`task:set_metric_score(name, score)`	Set the current score of metric `name`.
`task:set_metric_subject(subject)`	Set the subject in the default metric.
`task:learn(is_spam[, classifier)`	Learn classifier `classifier` with the task.
`task:set_settings(obj)`	Set users settings object for a task.
`task:set_settings_id(id)`	Set users settings id for a task (must be registered previously).
`task:get_settings()`	Gets users settings object for a task.
`task:lookup_settings(key)`	Gets users settings object with the specified key for a task.
`task:get_settings_id()`	Get numeric hash of settings id if specified for this task.
`task:set_milter_reply(obj)`	Set special reply for milter.
`task:process_re(params)`	Processes the specified regexp and returns number of captures (cached or new).
`task:cache_set(key, value)`	Store some value to the task cache.
`task:cache_get(key)`	Returns cached value or nil if nothing is cached.
`task:get_size()`	Returns size of the task in bytes (that includes headers + parts size).
`task:set_flag(flag_name[, set])`	Set specific flag for task.
`task:has_flag(flag_name)`	Checks for a specific flag in task.
`task:get_flags()`	Get list of flags for task.
`task:get_digest()`	Returns message's unique digest (32 hex symbols).
[`task:store_in_file([mode	table])`](#mbcdef)
`task:get_protocol_reply([flags])`	This method being called from a postfilter will return reply for a message.
`task:headers_foreach(callback, [params])`	This method calls `callback` for each header that satisfies some condition.
`task:disable_action(action)`	Disables some action for this task (e.g.
`task:get_newlines_type()`	Returns the most frequent newlines type met in a task.
`task:get_stat_tokens()`	Returns list of tables the statistical tokens.
`task:lookup_words(map, function({o, n, s, f}) ... end)`	Matches words in a task (including meta words) against some map (set, regexp and so on).
`task:get_dns_req()`	Get number of dns requests being sent in the task.
`task:add_timer(timeout, callback)`	Creates a delayed execution task for the specific callback at given timeout (in seconds).

Functions

The module rspamd_task defines the following functions.

Function `rspamd_task.create([cfg])`

Create a new empty task

Parameters:

No parameters

Returns:

{rspamd_task}: new task