Custom Encoders

Medis offers a range of built-in encoders, including MessagePack, Gzip, and PHP, which can convert the data stored in the database into a human-readable format. Furthermore, you have the option to create and use your own custom encoders.

A custom encoder is an executable shell script that communicates with Medis via standard input and output.

API

The API utilizes standard input and output. All content are encoded in Base64 before sending to deal with binary data.

Decode

When Medis opens a string key or the content field of a hash/set/zset/list... key, and the user selects a custom encoder, Medis will encode the content in Base64 and send to the encoder script via the standard input and pass decode parameter. The process is effectively similar to:

echo -n "-17" | base64 | ./encoder_Reverse.sh decode

Where encoder_Reverse.sh is a custom encoder.

Encode

Similarly, when the content is going to be saved to the database, Medis calls the custom encoder to encode the content with encode parameter.

Implement a Custom Encoder

In this section, we are going to demostrate how to implement a simple custom encoder that reverses the input.

Create a New File

All custom encoders need to be placed in a specific folder so Medis can find them. You can open the folder from Settings -> Encoder -> Open Encoder Folder.

Create a new file encoder_Reverse.sh inside the folder. It's worth noticing that the file name of custom encoders need to start with encoder_, otherwise they will be ignored.

Coding

Paste the following content into the file:

#!/bin/bash

# Set correct exit code when any commands fail so Medis can tell
# the user.
set -e
set -o pipefail

if [ $1 = "decode" ]; then
  # Get input from stdin
  input=$(cat)
  # Decode Base64
  decoded=$( base64 -d <<< $input )
  # Reverse the input
  reversed=$( echo -n $decoded | rev)
  # Encode in Base64
  echo -n $( echo -n $reversed | base64 )
elif [ $1 = "encode" ]; then
  echo "Encode not implemented!" 1>&2
  exit 1
fi

Make sure the output doesn't have newline chars. That's the reason we use echo -n.

The first shebang line is required so Medis can know how to run the script. It's possible to write the encoder in different languages as long as it has the correct shebang. For example, if you want to use Node.js, name the file with encoder_Reverse.js, and change the first line to:

#!/usr/local/bin/node

The shell script doesn't run your .bash_rc file so make sure you provide the absolute path instead of #!/usr/bin/env node.

Enable the Encoder

Then, add the executable permission to the script with chmod +x encoder_Reverse.sh. Then go to the encode setting panel and make sure our new encoder is enabled (you may need to click on the refresh button to see the encoder).

That's it! You can open a string key and select our new encoder. The content will get reversed. However, if we make some changes and save the content, Medis shows an error alert because we raise an error in the script when the parameter is encode. I will let you finish the script. For this encoder, encode and decode do the same thing, but other encoders may not.