Key-Value Store¶

The configuration store Storage is the built-in key-value store of FIRERPA with persistence. Even after FIRERPA or the device restarts, you can still read these variables on the next startup. This Storage allows you to persistently store information on the device for different client processes to read, enabling sharing of device configurations such as login accounts or other standalone information. You can even store encrypted configurations on the machine.

Attention

The total capacity of the built-in Storage is 128 MB, so do not use it to store large amounts of data. It does not support listing the container names or key names in the store. You must know the full container name and the key name in order to read a value from the container; otherwise, it will be permanently unreadable.

Get Storage¶

First, obtain a Storage object so that you can perform subsequent operations.

storage = d.stub("Storage")

Clear Storage¶

Clear all information in the Storage, including containers. You can simply think of this as – formatting the Storage.

storage.clear()

Get Container¶

Obtain a key-value store container object. The storage is the store itself, and a container is a bucket within the store. All subsequent reads and writes operate on this bucket.

container = storage.use("container_name")

Get Encrypted Container¶

If you also need to store values securely – for example, when the device might be used by other people and you do not want your stored configurations to be read by others – you can use an encrypted container. Unlike the simple container retrieval, the encrypted container will encrypt the key-value pairs you set, and others will need a password or other verification to read them.

Our library comes with a built-in FernetCryptor encryptor/decryptor. You can also implement your own unique encryption algorithm following the FernetCryptor pattern, as long as you implement the encrypt and decrypt methods.

from lamda.client import FernetCryptor
container = storage.use("container_name", cryptor=FernetCryptor,
                                          key="this_is_password")

Remove Container¶

Remove all key-value pairs stored in the container named container_name. This operation is equivalent to deleting the bucket.

storage.remove("container_name")

Write Key-Value to Container¶

Set the value of key_name to "value", where the value supports any msgpack-serializable variable.

container.set("key_name", [1, 2, 3])
container.set("key_name", {"john": "due"})
container.set("key_name", b"value")
container.set("key_name", "value")

Read Key-Value from Container¶

Get the value of key_name. If the key does not exist, None is returned.

container.get("key_name")

Get Time to Live¶

Get the time to live of key_name. -2 means the key does not exist, -1 means it never expires, and any other positive integer indicates the remaining seconds until the key expires.

container.ttl("key_name")

Set Time to Live¶

Set the time to live of a key-value pair. For example, the following call will set the key-value pair and cause it to be automatically deleted after 10 seconds.

container.setex("key_name", "value", 10)

Alternatively, if you have already set this key before and now want to assign a time to live, you can use expire. After 60 seconds, key_name will be automatically deleted.

container.expire("key_name", 60)

Conditional Write¶

Set the key-value pair only if key_name does not exist. If the key already exists, no operation is performed.

container.setnx("key_name", "value")

Check Existence¶

Check whether key_name exists in the container.

container.exists("key_name")

Delete Key-Value from Container¶

Delete key_name and its value from the container.

container.delete("key_name")