Cache module

Revision as of 16:06, 18 October 2012

This module implements in memory caches for LNP and CNAM.
Caches can be loaded from database or saved to database.

LNP handling

To mantain the LNP cache the module implements two call.route message handlers.

First handler

Check for querylnp=true in handled message.

Found: Look for the called number in cache. If the item is found copy its parameters in the call.route message, set querylnp=false and npdi=true parameters. If the item is not found set cache_lnp_posthook=true in the message to be handled in the second handler.

Not found: Look for npdi=true in handled message. If found and the cache is configured to store already done LNP the cache is updated.

The module should handle call.route before any other module(s) doing LNP requests.
The priority of the first handler should have a lower value (greater priority).

Second handler

The second handler is intended for cache update purpose only.
It should have a priority with a value between module(s) doing LNP and routing modules.
If the message don't have a cache_lnp_posthook=true parameter it will be ignored.
If LNP failed and the module is not configured to store failed requests the message will be ignored.

CNAM handling

To mantain the CNAM cache the module implements two call.preroute message handlers.

First handler

Check for querycnam=true in handled message.

Found: Look for the caller number in cache. If the item is found copy its parameters in the call.preroute message, set querycnam=false parameter. If the item is not found set cache_cnam_posthook=true in the message to be handled in the second handler.

Not found: The module will ignore the message.

The module should handle call.preroute before any other module(s) doing CNAM requests.
The priority of the first handler should have a lower value (greater priority).

Second handler

The second handler is intended for cache update purpose only.
It should have a priority with a value between module(s) doing CNAM and routing modules.
If the message don't have a cache_cnam_posthook=true parameter it will be ignored.
If CNAM failed and the module is not configured to store empty caller names the message will be ignored.

Commands

cache load cache_name [[param=value]...] 

Full or partial cache (re)load.

Parameters:

• cache_name: string: Required cache name
• id: string: Optional cache item id to (re)load. This parameter can be repeated
• delay: integer: Optional interval (in seconds) to delay (re)load operation

Examples

• cache load lnp delay=5 - Fully (re)load lnp cache. Wait 5 seconds before doing it
• cache load lnp id=123 id=999 - (Re)load 123 and 999 lnp cache items
• cache load lnp id= - Load nothing
• cache load lnp id - Invalid. The module will search for a cache named 'lnp id'

 cache flush cache_name [[param=value]...] 

Full or partial cache flush (delete).

Parameters:

• cache_name: string: Required cache name
• id: string: Optional cache item id to delete. This parameter can be repeated
• regexp: string: Optional cache item regexp to delete. All items matching the regexp will be removed. This parameter can be repeated

Examples:

• cache flush lnp - Clear the lnp cache
• cache flush lnp id=123 id=999 - Delete 123 and 999 from lnp cache
• cache flush lnp regexp=^888 - Delete all items starting with 888 from lnp cache
• cache flush lnp id= - Delete nothing
• cache flush lnp id - Invalid. The module will search for a cache named 'lnp id'

Configuration

File cache.conf:

; This file configures the cache module


[general]
; This section sets global variables of the implementation

; size: integer: The number of hash lists to use in each cache
; Defaults to 17, can't be less then 3 or greater then 1024
; This parameter can be overridden in cache sections
;size=17

; ttl: integer: Cache item time to live in seconds
; Minimum allowed value is 10
; This parameter is not applied on reload for already created cache objects
;ttl=

; limit: integer: Maximum number of stored cache items
; This value must be at least the power of 2 of cache hash list size, e.g. for
;  cache size 5 limit must be at least 25
; This parameter is applied on reload and can be overridden in cache sections
;limit=

; loadchunk: integer: The number of items to load in a database request
; Minimum allowed value is 500, maximum allowed value is 50000
; Set it to 0 to load the whole cache using a single database request
; This parameter is applied on reload and can be overridden in cache sections
; NOTES for non 0 value:
; - The 'query_loadcache' parameter in cache sections should contain an 'ORDER BY'
;   clause to make sure the cache table is parsed in the same order
; - The 'query_loadcache' query MUST be a parameterized query containing
;   LIMIT ${chunk} OFFSET ${offset}. The module will replace chunk and offset for each
;   sent database request
;loadchunk=0

; maxchunks: integer: Maximum number of chunks to load from cache
; Minimum allowed value is 1, maximum allowed value is 10000
; Defaults to 1000
; This parameter is applied on reload
; WARNING:
; - Set a large value only if you are sure the cache load queries are correct
; - Setting a large value for a query without LIMIT or OFFSET will lead to
;    useless extra processing
;maxchunks=1000

; loadcache_priority: keyword: The priority of the cache load thread

This parameter is applied on reload and can be overridden in cache sections

; Can be one of: lowest, low, normal, high, highest
; High priorities need superuser privileges on POSIX operating systems
; Defaults to normal
;loadcache_priority=normal

; expire_check_interval: integer: The interval (in seconds) to check cache expire
; Defaults to 10, minimum allowed value 1, maximum allowed value 300
; This parameter is applied on reload
;expire_check_interval=10

; account: string: Database name
; This parameter is applied on reload and can be overridden in cache sections
;account=

; account_loadcache: string: Optional database account used to load an entire cache
; This parameter is applied on reload and can be overridden in cache sections
;account_loadcache=


; The following parameters can be set in cache sections

; reload_interval: integer: Interval (in seconds) to reload the cache
; This parameter is applied on reload
; This parameter will be ignored if the cache don't have a load account and query
; Minimum allowed value is 10. Set it to 0 to disable cache reload
; Defaults to 0 (no reload)
;reload_interval=0


[lnp]
; This section configures the LNP cache
; Database query examples assume a 'lnp' table with the following fields:
; - id TEXT The called number
; - routing TEXT Routing number (may be empty)
; - timeout TIMESTAMP Expire time

; enable: boolean: Enable LNP cache
; Defaults to no
; This parameter is applied on reload
;enable=no

; store_failed_requests: boolean: Store failed LNP requests in cache
; Defaults to no
; This parameter is applied on reload
;store_npdi_before=no

; id_param: string: Template used to build a cache entry id value when handling messages
; This parameter is applied on reload
; Defaults to called party number parameter (the id is retrieved from the 'called'
;  parameter value of handled messages)
;id_param=${called}

; copyparams: string: Parameters to handle (store in cache or copy to handled messages)
; This parameter is applied on reload and can be overridden when routing by
;  a 'cache_lnp_parameters' parameter
;copyparams=routing

; routebefore: integer: The priority of the call.route message handler used to
;  intercept incoming calls and set the routing number if found in cache or
;  update the cache if LNP was already done
; Defaults to 25
;routebefore=25

; routeafter: integer: The priority of the call.route message handler used to
;  intercept the message after LNP was done locally and update the cache
; Defaults to 75
;routeafter=75
 
; query_loadcache: string: Database query used to load the LNP cache when created
; This parameter is applied on reload
;query_loadcache=SELECT FLOOR(EXTRACT('EPOCH' FROM (timeout - CURRENT_TIMESTAMP))) AS expires,* FROM lnp
; For non 0 'loadchunk'
;query_loadcache=SELECT FLOOR(EXTRACT('EPOCH' FROM (timeout - CURRENT_TIMESTAMP))) AS expires,* FROM lnp ORDER BY timeout LIMIT ${chunk} OFFSET ${offset}

; query_loaditem: string: Database query used to load an item when requested and not found
;  in cache
; This parameter is applied on reload
;query_loaditem=SELECT FLOOR(EXTRACT('EPOCH' FROM (timeout - CURRENT_TIMESTAMP))) AS expires,* FROM lnp WHERE id='${id}'
 
; query_loaditem_command: string: Database query used to load an item when handling
;  a 'cacheload' command indicating specific items(s)
; This parameter is applied on reload
; Defaults to the value of query_loaditem
;query_loaditem_command=SELECT FLOOR(EXTRACT('EPOCH' FROM (timeout - CURRENT_TIMESTAMP))) AS expires,* FROM lnp WHERE id='${id}'
 
; query_save: string: Database query used to save an item
; This parameter is applied on reload
;shortest_prefix=0


[cnam]
; This section configures the CNAM cache
; Database query examples assume a 'cnam' table with the following fields:
; - id TEXT The caller number
; - callername TEXT Caller's name (may be empty)
; - timeout TIMESTAMP Expire time

; enable: boolean: Enable CNAM cache
; Defaults to no
; This parameter is applied on reload
;enable=no

; store_empty: boolean: Store empty caller name returned by local CNAM query in cache
; Defaults to no
; This parameter is applied on reload
;store_empty=no

; id_param: string: Template used to build a cache entry id value when handling messages
; This parameter is applied on reload
; Defaults to caller party number parameter (the id is retrieved from the 'caller'
;  parameter value of handled messages)
;id_param=${caller}

; copyparams: string: Parameters to handle (store in cache or copy to handled messages)
; This parameter is applied on reload and can be overridden when routing by
;  a 'cache_cnam_parameters' parameter
;copyparams=callername

; routebefore: integer: The priority of the call.preroute message handler used to
;  intercept incoming calls and set the callername if found in cache or
;  update the cache from caller name
; Defaults to 25
;routebefore=25

; routeafter: integer: The priority of the call.preroute message handler used to
;  intercept the message after CNAM was done locally and update the cache
; Defaults to 75
;routeafter=75

; query_loadcache: string: Database query used to load the CNAM cache when created
; This parameter is applied on reload
;query_loadcache=SELECT FLOOR(EXTRACT('EPOCH' FROM (timeout - CURRENT_TIMESTAMP))) AS expires,* FROM cnam
; For non 0 'loadchunk'
;query_loadcache=SELECT FLOOR(EXTRACT('EPOCH' FROM (timeout - CURRENT_TIMESTAMP))) AS expires,* FROM cnam ORDER BY timeout LIMIT ${chunk} OFFSET ${offset}

; query_loaditem: string: Database query used to load an item when requested and not found
;  in cache
; This parameter is applied on reload
;query_loaditem=SELECT FLOOR(EXTRACT('EPOCH' FROM (timeout - CURRENT_TIMESTAMP))) AS expires,* FROM cnam WHERE id='${id}'

; query_loaditem_command: string: Database query used to load an item when handling
;  a 'cacheload' command indicating specific items(s)
; This parameter is applied on reload
; Defaults to the value of query_loaditem
;query_loaditem_command=SELECT FLOOR(EXTRACT('EPOCH' FROM (timeout - CURRENT_TIMESTAMP))) AS expires,* FROM cnam WHERE id='${id}'

; query_save: string: Database query used to save an item
; This parameter is applied on reload
;query_save=INSERT INTO cnam(id,callername,timeout) VALUES('${id}','${callername}',CURRENT_TIMESTAMP + INTERVAL '${expires} s')

; query_expire: string: Database query used to expire items
; This parameter is applied on reload
;query_expire=DELETE FROM cnam WHERE CURRENT_TIMESTAMP >= timeout

; shortest_prefix: integer: Minimum cache element length that can be a prefix match
; Valid values 1-32, a value of 0 disables cache prefix matching
; This parameter is applied on reload
;shortest_prefix=0