Building Extensions

!!! This section is a work in progress !!!

Public/Private Limitations

Anyone can build Extensions for LimaCharlie. The only limit is put on making an Extension public. Private extensions require the owner of the extension to have the billing.ctrl and user.ctrl permission on an organization in order to subscribe the organization to the private extension.

If you'd like to make your extension public (and/or monetize it), reach out to answers@limacharlie.io and we'll help you out. Once public, an extension is visible by everyone and can subscribed by everyone.

High Level Structure

Extensions are small services that receive webhooks from LimaCharlie. This means building an extension requires exposing a small HTTPS service to the internet. We recommend using something like Google Cloud Run, but ultimately you could also use AWS Lambdas or even host on your own hardware.

This https server will communicate with the LimaCharlie cloud according to a simple protocol using JSON.
That being said, don't worry, you don't need to know the underlying way the extension protocol works as long as you're comfortable with our public implementations:

• Golang: https://github.com/refractionPOINT/lc-extension
• Python: https://github.com/refractionPOINT/lc-extension/tree/master/python

Using one of these frameworks, you'll only have to implement the little bits of user code you care about.

Convenience

Building functionality as a LimaCharlie Extension provides you specific convenience:

• Multi-tenancy: LC organizations can subscribe to your extension and you can replicate the features you're building across tenants.
• Credentials handling: you don't need to store any credentials from LC organizations. Every callback you receive will include an authenticated LimaCharlie SDK for the organization relevant to the callback, with the permissions you requesed for the extension.
• Configuration: you're always welcome to store some configuration wherever the extension lives, but as a convenience LC will provide you with a configuration JSON object for your extension (stored in Hive) and with a callback for you to validate the content of the configuration when a user makes a modification.
• GUI: each extension defines its own Schema, a structure indicating to LimaCharlie what actions the extension exposes, how to call it and what to expect as a return value from actions. This information is then automatically interpreted by LimaCharlie to generate a custom user interface for your extension, making it extremely easy to expose new functionality in LimaCharlie without having to build any kind of UI (though you're always free to build one if you'd like).

Core Concepts

Let's dig in to some of the core concepts of building an extension. Although those concepts are generally the same across different implementations, we'll use Golang as a reference since it provides stricter typing and it rocks.

Extension Definition

Each extension is defined at the time of creation. We'll skip over the various descriptions and info fields and focus on the more important aspects of building the extension:

• Destination URL: this is the HTTPS URL where your extension will be reachable at.
• Required Extensions: this is the list of other extensions your extension assumes it will have access to. When an org subscribes and is missing one of those, the user will be prompted to subscribe to these.
• Shared Secret: this is an arbitrary string that will be used by LimaCharlie and your extension to sign webhooks to your extension, allowing it to very the authenticity of the hook. Make it something at least 32 characters and random.
• Extension Flairs: these are modifiers that will be applied to your extension. Namely the segment flair will isolate the resources the extension can access so that it can only see and modify things (like D&R rules) that it has created, making it great for extensions that need a narrow scope, you should enable it unless you know you need it off. The bulk flair tells LimaCharlie that it expects to make a lot of API calls to the LC cloud, which will increase the API quota for the extension.
• Permissions: the list of permissions this extension requires on each organization subscribed to it. Use the least amount of permissions possible.

Schema

...

https://github.com/refractionPOINT/lc-extension/blob/master/common/config_schema.go

// build out your api service and schema using as primitive data types as you are familiar with (such as string, bool, number), and then use that to test out your extension.

Request Schema

Config Schema

The config schema is a description of what the extension's config should look like, when stored as a Hive record in the extension_configuration Hive for convenience.

Response Schema (optional)

Callbacks

Callbacks are functionality that an extension can specify whenever some type of event occurs.

Configuration Validation Callback

This callback is used by LimaCharlie to check the validity of a change in configuration done in Hive. If the configuration is valid, return success, otherwise you can return an error.

Event Callback

Events are events generated by the LimaCharlie platform outside your control. Currently, these 3 events are supported:

• subscribe: called when an organization subscribes to an extension.
• unsubscribe: called when an organization unsubscribes from an extension.
• update: called once a day per organization subscribed to the extension. It is a convenient way to perform updates to an organization like when needing to update D&R rules used by the extension.

Your extension will only receive these events if they were specified as of-interest in the extension's Schema.

Request Callback

The requests are the core way users, D&R rules or other extensions can interact with your extension. You can define one callback per action. It is common for an extension to have multiple actions, some public (for user-generated requests) and some private (to be used internally by the extension in the course of doing whatever it does).

Simplified Frameworks

The Golang implementation of Extensions provides 3 different simplified frameworks to make the job of producing a new extension more straight forward in specific cases: https://github.com/refractionPOINT/lc-extension/tree/master/simplified

D&R

This simplified framework, found in dr.go allows you to package D&R rules as an extension making it easy for you to distribute and update D&R rules to many orgs. Its core mechanism is based on defining the GetRules() function and returning a structure like map[DR-Namespace]map[RuleName]RuleContent. The simplified framework takes care of the recurring updates and everything else.

Lookup

Similarl to the D&R simplified framework, but is used to package Lookups. Example: https://github.com/refractionPOINT/lc-extension/blob/master/examples/lookup/main.go

CLI

This simplified framework serves to streamline the integration of 3rd party Command Line Interface tools so that they can be automated using LimaCharlie, often bringing bi-directionality to the platform.