Collaboration diagram for Rules Processing:

Data Structures
struct	rules_request

Typedefs
typedef bool(*	rules_flags_upcall) (struct rules_request *self)
	Rules upcall for flags; used when FLAGS are encountered in a Rule. More...

typedef bool(*	rules_trigger_upcall) (struct rules_request *self, rules_trigger trigger_name, unsigned tigger_namelen)
	Rules upcall for triggers; used ^trigger is encountered in a Rule. More...

typedef bool(*	rules_selector_upcall) (struct rules_request self, const a2sel_t selector)
	Rules upcall for selectors; used when ~sel is encountered in a Rule. More...

typedef bool(*	rules_endrule_upcall) (struct rules_request *self)
	Rules upcall for the end of a Rule. More...

typedef bool(*	rules_endruleset_upcall) (struct rules_request *self)
	Rules upcall for the end of a Ruleset. More...

Functions
void	rules_init (void)
	Initialise the ARPA2 Rules system. More...

void	rules_fini (void)
	Finalise the ARPA2 Rules system. More...

bool	rules_process (struct rules_request req, const char ruleset, unsigned rulesetlen, bool permit_selector)
	Process a Ruleset, causing upcalls as specified in the rules_request. The ruleset is the ext to process, with a NUL character ending individual Rules, and with rulesetlen to mark the total length. More...

bool	rules_dbiterate (struct rules_request req, const uint8_t svckey, unsigned svckeylen, const rules_name name, const a2sel_t *iter0)
	Iterate over an ARPA2 Selector for an identity to find the most concrete Ruleset; once found, process it. More...

Detailed Description

Rules processing comes down to parsing a Ruleset and triggering upcalls for them. These upcalls process the FLAGS, ^triggers and ~selectors while taking =variables into account. Special upcalls for the end of a Rule and the end of a Ruleset can be used to collate and make decisions on what should pass.

Processing always passes over the entire Ruleset. As soon as a syntax error is found, processing breaks off and no further callbacks are made. The upcall at the end of the entire Ruleset is made exactly when no processing error has occurred.

The variables are references into the Ruleset, and once Ruleset processing ends the underlying memory may have gone, so the last opportunity for keeping the values found is in the upcall at the end of the Ruleset.

There are two kinds of Ruleset processing, reflecting two kinds of input data. One for a literal Ruleset found nearby a Resource or stored in an LDAP attribute accessRule. The other is retrieved from the database by normal ARPA2 Iteration up from an ARPA2 Identity. In the latter case, the underlying database is assumed to be the default database, which is opened for a short-lived transaction without any need for the calling program to mention the database. The Service Key suffice to find the desired Rules, after expansion for the identity and its more abstract forms.

Applications that build on top of Rules, such as Access Control or Groups, will generally wrap around both forms as Ruleset processing to support both resource-local specifications and database-centralised and bulk-maintainable Rules.

Typedef Documentation

◆ rules_endrule_upcall

typedef bool(* rules_endrule_upcall) (struct rules_request *self)

Rules upcall for the end of a Rule.

The intention of this upcall is to support a choice between the current Rule and offerings that may have been made before. In other words, to collate and choose.

After return from this upcall, the Rule Flags and Variables will be emptied in the rules_request structure.

This upcall is at the end of any Rule, even for the last. If it is the last, then rules_endruleset_upcall will be called immediately afterward.

Returns: Always return true for future compatibility.

◆ rules_endruleset_upcall

typedef bool(* rules_endruleset_upcall) (struct rules_request *self)

Rules upcall for the end of a Ruleset.

This upcall is made after a complete Ruleset has been parsed successfully. It is skipped for syntax errors.

The intention of this upcall is to given a last opportunity to process any data collected and decided about in the foregoing upcalls. The Rules Flags and Variables cannot be assumed to present during this call. The underlying memory for the collected information is however still present, and at the brink of being removed. Use it or loose it, meaning if you need retention beyond this point you should make a copy in your own data structures.

Returns: Always return true for future compatibility.

◆ rules_flags_upcall

typedef bool(* rules_flags_upcall) (struct rules_request *self)

Rules upcall for flags; used when FLAGS are encountered in a Rule.

Returns: Always return true for future compatibility.

◆ rules_selector_upcall

typedef bool(* rules_selector_upcall) (struct rules_request *self, const a2sel_t *selector)

Rules upcall for selectors; used when ~sel is encountered in a Rule.

Returns: Always return true for future compatibility.

◆ rules_trigger_upcall

typedef bool(* rules_trigger_upcall) (struct rules_request *self, rules_trigger trigger_name, unsigned tigger_namelen)

Rules upcall for triggers; used ^trigger is encountered in a Rule.

Returns: Always return true for future compatibility.

Function Documentation

◆ rules_dbiterate()

bool rules_dbiterate	(	struct rules_request *	req,
		const uint8_t *	svckey,
		unsigned	svckeylen,
		const rules_name	name,
		const a2sel_t *	iter0
	)

Iterate over an ARPA2 Selector for an identity to find the most concrete Ruleset; once found, process it.

Standard ARPA2 Iteration starts with iter0 and moves from concrete to abstract. The first (and most concrete) record found is the only one being processed and it triggers the upcalls that are specified in the req input. When no ruleset is found at all, the function returns false and sets errno to Common Error code A2XS_ERR_MISSING_RULESET.

The svckey with length svckeylength identifies the Service Key, usually derived from a Rules Domain, Rules Type and optional Database Secret with rules_dbkey_domain() and rules_dbkey_service().

It may happen that no upcalls are made. There may be no Ruleset or it may run into syntax errors. Specifically the upcall for the end of the Ruleset indicates that no problems occurred.

This function invokes ruleset_process() unless this is overridden with non-NULL ruleset_process_override in the req parameter. During the call, optcb_selector will be set to NULL and opt_qiter is the Quick Iterator that was found in the database and opt_name will be set to name.

Returns: The return value is true for succes, or false with errno set to a Common Error code on failure.

◆ rules_fini()

void rules_fini ( void )

Finalise the ARPA2 Rules system.

This may do cleanup operations.

◆ rules_init()

void rules_init ( void )

Initialise the ARPA2 Rules system.

This has a mirror image for cleaup in rules_fini().

◆ rules_process()

bool rules_process	(	struct rules_request *	req,
		const char *	ruleset,
		unsigned	rulesetlen,
		bool	permit_selector
	)

Process a Ruleset, causing upcalls as specified in the rules_request. The ruleset is the ext to process, with a NUL character ending individual Rules, and with rulesetlen to mark the total length.

When permit_selector is true, the form ~selector is permitted; an LDAP accessRule as well as localised settings near a serviced resource would contain this form and set permit_selector to true, while an LMDB rule would parse to a known remote and forbid ~selector words.