Sieve memcache extension

From Messaging Server Technical Reference Wiki
Jump to: navigation, search


As of the 8.0 release, the MTA supports a private "memcache" operator, which may be used to perform both actions and tests. (Configuration of MTA connections to memcache is required; see the Memcache MTA options and in particular see the memcache_host MTA option which requires an explicit, valid value.) This nonstandard extension is available without any special capability declaration; no "require" action is needed for its use. By default, the "memcache" operator may be used in any Sieve script, but its availability may be selectively disabled via the enable_sieve_memcache MTA option. This extension is provided so that Sieve filters can access and manipulate data using the memcache protocol.

The various Sieve "memcache" operations share a set of common nonpositional parameters:

:host host-string
Specifies the host name(s) and port(s) for the memcached server to use in host:port format. The port part is optional and defaults to value given to the memcache_port MTA option. If ":host" isn't specified, the host and port are given by the memcache_host and memcache_port MTA options respectively.
:host [host-string1, host-string2, ...]
If a list of host:port pairs is specified, one will be chosen by applying a hash function to the key. This provides the means to distribute key-value pairs across multiple memcache servers. Note that the algorithm used is the same as for the memcache mapping callout.
:tableprefix prefix-string
Unlike MeterMaid, each memcache server provides a single storage area; in effect a single "table". Multiple tables can be implemented by adding a prefix to the key. ":tableprefix" provides a convenient way to specify such a prefix while making it clear that the string is a prefix and not logically part of the key. (Note that some servers that implement the memcache protocol impose additional structure on the key themselves; the ":tableprefix" parameter may be useful in specifying such structure.)
:timeout timeout-number
Specifies the timeout value in seconds for the entry being created or updated. The default timeout value is 0, which means the entry never times out.
:quota quota-int
Specifies the maximum number of counts to permit during the quota timeout period. This corresponds to MeterMaid throttle table quota setting.
:quotatimeout quota-timeout-int
Specifies the duration in seconds of the period over which counts are recorded. This corresponds to MeterMaid throttle table quota_time setting.
:penalize
Corresponds to MeterMaid throttle table option penalize setting.
:limit
(New in MS 8.0.2.3.) Normally :throttle operations update the throttle even when the throttle engages; this is appropriate when throttling an external activity that occurs outside the control of Messaging Server. The addition of :limit causes a :throttle test to only update when the throttle does not engage; this is appropriate when a throttle is being used to limit some internal activity that doesn't occur when the throttle engages. Any operation failure is also handled in a failsafe manner when :limit is specified - server down, network failure, wrong data type, etc. - to return TRUE rather than the usual FALSE.
:duplicate
It may be necessary to evaluate Sieves more than once, e.g., when a message is sent to multiple recipients and the Sieve employs an envelope "to" test. Additionally, even if a particular Sieve script does not contain such a test, it may nevertheless be necessary to reevaluate it if a previous script was reevaluated and that action changed one or more of the inputs to the current script.
It is undesirable in most cases to reevaluate memcache actions that perform increment, decrement, append, or prepend operations. As such, most memcache operations are skipped when a script is reevaluated. (The exact behavior is noted in each section below.)
However, there are cases, e.g., when using recipient-specific data, when reevaluation is the correct action. The ":duplicate" nonpositional parameter provides this capability: if specified, the associated memcache operation will be performed on both initial and subsequent evaluations.
MATCH-TYPE and COMPARATOR
See RFC 5228 for information about MATCH-TYPE and COMPARATOR parameters.

The memcache Sieve extension provides the following operations:


  memcache :add  [:host host-string] [:tableprefix prefix-string]
           [:duplicate] [:timeout timeout-number] key-string
           value-string

Add a new entry with the specified key, value and timeout. The operation only suceeds if the entry does not already exist. The operation returns TRUE if the entry is added successfully, FALSE if not. For example:


      if not memcache :add "a" "b" { ... handle failure ... }

memcache ":add" operations are skipped and return success unconditionally on script reevaluations by default. ":duplicate" forces the operation to be performed on all reevaluations.


  memcache :adjustdown adjustment-value [:host host-string]
           [:tableprefix prefix-string] [:duplicate] [MATCH-TYPE]
           [COMPARATOR] [:quotatimeout quotatimeout-numeric [:penalize]]
           [:timeout timeout-value] key-string [test-string]

Decrement the entry with the specified key by the specified adjustment value. The entry must contain an unsigned decimal string. The adjustment value can be either an integer or a string; if it is a string it must contain an optionally signed decimal value. Negative adjustment value are allowed and will be converted into an appropriate increment operation.

The specified entry will be created (with a value of 0) prior to adjustment if it doesn't already exist. The timeout value is only used if the entry has to be created.

memcache ":adjustdown" operations can be applied to throttle entries. If this is done, the appropriate quota parameters must be specified in case the entry needs to be created.

Note that memcache's increment and decrement operations do not support negative values. Attempts to decrement an entry to a value below 0 will result in a 0 value being stored.

The adjusted value is returned as an unsigned decimal string if neither MATCH-TYPE, COMPARATOR, nor test-string are specified. However, if any of these parameters are specified this operation functions as a test with updated value of the entry being the tested value. MATCH-TYPE and COMPARATOR default to :value "lt" and "i;ascii-numeric" respectively. For example:


      if memcache :adjustdown 1 "entry" "10" {
        ... handle entry less than 10 ... }

memcache ":adjustdown" operations are performed on reevaluations but the adjustment amount is changed to 0. ":duplicate" causes the adjustment amount to be retained on reevaluations.


  memcache :adjustup adjustment-value [:host host-string]
           [:tableprefix prefix-string] [:duplicate] [MATCH-TYPE]
           [COMPARATOR] [:quotatimeout quotatimeout-numeric [:penalize]]
           [:timeout timeout-value] key-string [test-string]

Increment the entry with the specified key by the specified adjustment value. The entry must contain an unsigned decimal string. The adjustment value can be either an integer or a string; if it is a string it must contain an optionally signed decimal value. Negative adjustments values are allowed and will be converted into an appropriate decrement operation.

The specified entry will be created (with a value of 0) prior to adjustment if it doesn't already exist. The timeout value is only used if the entry has to be created.

memcache ":adjustup" operations can be applied to throttle entries. If this is done, the appropriate quota parameters must be specified in case the entry needs to be created.

The adjusted value is returned as an unsigned decimal string if if neither MATCH-TYPE, COMPARATOR, nor test-string are specified. However, if any of these parameters are specified this operation functions as a test with updated value of the entry being the tested value. MATCH-TYPE and COMPARATOR default to :value "gt" and "i;ascii-numeric" respectively. For example:


if memcache :adjustup 1 "entry" "10" { ... handle entry greater than 10 ... }

memcache ":adjustup" operations are performed on reevaluations but the adjustment amount is changed to 0. ":duplicate" causes the adjustment amount to be retained on reevaluations.


  memcache :append [:host host-string] [:tableprefix prefix-string]
           [:duplicate] key-string value-string

Append the specified value to the entry with the specified key. The entry must already exist. Returns TRUE if the operation is successful, FALSE if it is not.

memcache ":append" operations are skipped and return success unconditionally on reevaluations by default. ":duplicate" forces the operation to be performed on all reevaluations.


  memcache :fetch [:host host-string] [:tableprefix prefix-string]
           [MATCH-TYPE] [COMPARATOR] key-string [test-string]

Fetches the value of the entry with the specified key.

The entry's value is simply returned as a string if neither MATCH-TYPE, COMPARATOR, nor test-string are specified. An empty string will be returned if the specified entry doesn't exist.

However, if any of the three parameters are specified this operation functions as a test with current value of the entry being the tested value. MATCH-TYPE and COMPARATOR default to :is and "i;ascii-casemap" respectively. The test always fails if the entry does not exist. This can be to test for the existence of an entry:


if memcache :fetch :matches "entry" "*" { ... entry exists ... }

memcache ":fetch" operations are simply repeated on reevaluations.


  memcache :prepend [:host host-string] [:tableprefix prefix-string]
           [:duplicate] key-string value-string

Prepend the specified value to the entry with the specified key. The entry must already exist. Returns TRUE if the operation is successful, FALSE if it is not.

memcache ":prepend" operations are skipped and return success unconditionally on reevaluations by default. ":duplicate" forces the operation to be performed on all reevaluations.


  memcache :release [:duplicate]
           [:host host-string] [:tableprefix prefix-string]
           [:timeout timeout-value]  key-string

Implements a generic reservation capability, where a specified key-string can be repeatedly reserved up to a specified quota. :release releases a reservation previously created by :reserve. The associated memcache entry contains a record of how many reservations are held by each process on the host. Outstanding reservations associated with nonexistent processes will be automatically deteled.

This operation always functions as a test, returning TRUE if the reservatation has been releaves succesfully, FALSE otherwise.

memcache reservation operations are performed on reevaluations.


  memcache :remove [:host host-string] [:tableprefix prefix-string]
           [:duplicate] [:lockout lockout-numeric] key-string

Remove the entry with the specified key. A lockout value, if specified, is an unsigned integer specifying the amount of time to "lock" the key - during that time attempts to store an entry with that key will fail. A lockout default of 0 is the default and causes no lockout to occur. Returns TRUE if the operation is successful, FALSE if it is not.

memcache ":remove" operations are skipped and return success unconditionally on reevaluations by default. ":duplicate" forces the operation to be performed on all reevaluations.


  memcache :replace [:host host-string] [:tableprefix prefix-string]
           [:timeout timeout-value] key-string value-string

Update the value and timeout of an entry. The entry must already exist. Returns TRUE if the operation is successful, FALSE if it is not.

memcache ":replace" operations are simply repeated on reevaluations.


  memcache :reserve :quota quota-numeric [:duplicate]
           [:host host-string] [:tableprefix prefix-string]
           [:timeout timeout-value]  key-string

Implements a generic reservation capability, where a specified key-string can be repeatedly reserved up to a specified quota. Each reserve operation must be matched by a corresponding release. The associated memcache entry contains a record of how many reservations are held by each process on the host. Outstanding reservations associated with nonexistent processes will be automatically deteled.

Note that since there is no server-side awareness of entry semantics the quota parameter must be specified in every reserve call in case the entry needs to be created. If the entry already exists the quota parameter value will be checked against the corresponding value stored in the entry.

Each reserve operation increments the reservation count by 1, and should be matched by a corresponding release operation.

This operation always functions as a test, returning TRUE if the reservation is successful, FALSE otherwise.

memcache reservation operations are performed on reevaluations.


  memcache :store [:host host-string] [:tableprefix prefix-string]
           [:timeout timeout-value] key-string value-string

Creates a new entry or updates an existing entry with the specified key, value and timeout. Returns TRUE if the operation is successful, FALSE if it is not.

memcache ":store" operations are simply repeated on reevaluations.


  memcache :throttle :quota quota-numeric [:duplicate]
           :quotatimeout quotatimeout-numeric [:penalize] [:limit]
           [:host host-string] [:tableprefix prefix-string]
           [:timeout timeout-value] [MATCH-TYPE] [COMPARATOR]
           [:adjustup adjustment-value] [:adjustdown adjustment-value]
           key-string [test-string] 

Implements the MeterMaid throttle capability. See the MeterMaid documentation for details of throttle semantics. Note that since there is no server-side awareness of entry semantics the quota and quotatimeout parameters must be specified in every throttle call in case the entry needs to be created. If the entry already exists the parameter values will be checked against the corresponding values stored in the entry.

The throttle value is incremented by default. Either ":adjustup" or ":adjustdown" can be used to specify an alternate adjustment value. (Note that in this case these nonpositional parameters function as modifiers, not operation specifiers.)

New in MS 8.0.2.3, ":limit" can be specified to prevent the throttle from being adjusted if it engages and to behave in a failsafe fashion.

This operation always functions as a test. If neither MATCH-TYPE, COMPARATOR, nor test-string are specified TRUE is returned if the throttle is engaged, FALSE if it is not engaged or an error occurs. If one of these three parameters is provided the throttle is adjusted and then Sieve tests are applied to the adjusted value. The default MATCH-TYPE is :value "gt" and the default COMPARATOR is "i;ascii-numeric".

memcache ":throttle" operations are performed on reevaluations but the adjustment amount is changed to 0. ":duplicate" causes the adjustment amount to be retained on script reevaluations.


See also: