FTN14: FutoIn Cache
Version: 1.0
Date: 2015-01-22
Copyright: 2014 FutoIn Project (http://futoin.org)
Authors: Andrey Galkin

CHANGES

• v1.0 - 2015-01-22

1. Concept

This spec is trying to be as simple as possible to meet very basic needs of caching.

It it expected that Service implementation handles cache hammering mitigation (e.g. by "expiring" ttl for some get requests 10% earlier).

2. Interface schema

    {
        "iface" : "futoin.cache",
        "version" : "{ver}",
        "ftn3rev" : "1.1",
        "funcs" : {
            "get" : {
                "params" : {
                    "key" : {
                        "type" : "string",
                        "desc" : "Unique cache key"
                    }
                },
                "result" : {
                    "value" : {
                        "type" : "any",
                        "desc" : "Any previously cached value"
                    }
                },
                "throws" : [
                    "CacheMiss"
                ],
                "desc" : "Trivial cached value retrieval"
            },
            "set" : {
                "params" : {
                    "key" : {
                        "type" : "string",
                        "desc" : "Unique cache key"
                    },
                    "value" : {
                        "type" : "any",
                        "desc" : "arbitrary value to cache"
                    },
                    "ttl" : {
                        "type" : "integer",
                        "desc" : "Time to live in milliseconds"
                    }
                },
                "desc" : "Trivial cached value storing"
            },
            "custom" : {
                "params" : {
                    "cmd" : {
                        "type" : "string",
                        "desc" : "Implementation-defined custom command"
                    },
                    "prm" : {
                        "type" : "any",
                        "desc" : "Implementation-defined custom command parameters"
                    }
                }
            }
        },
        "requires" : [
            "SecureChannel"
        ],
        "desc" : "Audit Log interface"
    }

3. Native interface

• Extend "futoin.cache"
• Functions:
  • void getOrSet( as, key_prefix, callable, params, ttl )
    • key_prefix - unique key prefix
    • callable( as, params.. ) - a callable which is called to generated value on cache miss
    • params - parameters to be passed to callable
    • tt - time to live to use, if value is set on cache miss
    • NOTE: the actual cache key is formed with concatenation of key_prefix and join of params values
    • NOTE: cache hammering mitigation logic should be implemented on Service side to achieve single execution of callable per cache miss

=END OF SPEC=