All functions described here are bindings that are generated from our provider protocol and which are publish as our provider bindings crate. Please refer to the crate for more details on any of the types mentioned below.
We use fp-bindgen
for generating the bindings themselves.
Exported functions
Exported functions are functions that your provider implements, and that the runtime will call. In order to make those exported functions usable in Fiberplane, they must be annotated with #[pdk_export]
.
get_supported_query_types
get_supported_query_types
It is advised to use the Provider Development Kit rather than implementing this function manually. The pdk_query_types!
macro can be used to generate this function for you. See the tutorial for more information about using the PDK.
Signature
pub async fn get_supported_query_types(config: ProviderConfig) -> Vec<SupportedQueryType>;
Description
Returns the query types supported by this provider. This function allows Studio to know upfront which formats will be supported, and which providers (and their query types) are eligible to be selected for certain use cases.
invoke2
invoke2
It is advised to use the Provider Development Kit rather than implementing this function manually. The pdk_query_types!
macro can be used to generate this function for you. See the tutorial for more information about using the PDK.
Signature
pub async fn invoke2(request: ProviderRequest) -> Result<Blob>;
Description
Invokes the provider to perform a data request.
create_cells
(Optional)
create_cells
(Optional)Signature
pub fn create_cells(query_type: String, response: Blob) -> Result<Vec<Cell>>;
Description
Creates output cells based on the response (a Blob
that the provider previously sent to answer an invoke2
call). Studio would typically embed the created cells in the provider cell, but other actions could be desired.
When any created cells use a data-links
field with the value cell-data:<mime-type>,self
(such as Log cells or Graph cells), Studio will replace the value self
with the ID of the cell for which the query was invoked. This allows the provider to create cells that reference its own data without knowing the context of the cell in which it was executed.
Note that implementing create_cells
is optional. If invoke2
returns a Blob with a MIME type of application/vnd.fiberplane.cells
(suffixed with either +json
or +msgpack
), that response will be parsed into an array of cells, and the call to this function is elided. A consequence of this approach is that the blob with the response does not get stored on the provider cell -- only the parsed cells will be stored. This can make this approach less suitable for graph cells and log cells, for instance, but makes it more efficient when there is no need to refer to the data after the cells are instantiated.
extract_data
(Optional)
extract_data
(Optional)Signature
pub fn extract_data(response: Blob, mime_type: String, query: Option<String>) -> Result<Blob>;
Description
Takes the response data, and returns it in the given MIME type, optionally passing an additional query string to customize extraction behavior.
Returns Err(Error::UnsupportedRequest)
if an unsupported MIME type is passed.
Please be aware that in order for Studio to parse response blobs, the MIME type has to specify the encoding format, using either the +json
or +msgpack
suffix. This applies to all the MIME types recognized by Studio, such as:
application/vnd.fiberplane.cells
application/vnd.fiberplane.events
application/vnd.fiberplane.timeseries
While Blobs must specify the encoding suffix for their data to be correctly parsed, the mime_type
that is requested does not specify it. The implementation is then free to decide which encoding to use for the blob it returns.
When deriving the ProviderData
trait, its to_blob()
helper will automatically pick a suitable encoding for you.
Note: When the MIME type in the provider response is the same as the MIME type given as the second argument (sans encoding suffix), and the query
is omitted, the return value is expected to be equivalent to the raw response data. This means Studio should be allowed to elide calls to this function if there is no query string and the MIME type is an exact match. This elision should not change the outcome.
get_config_schema
(Optional)
get_config_schema
(Optional)Signature
pub fn get_config_schema() -> ConfigSchema;
Description
Returns the schema for the config consumed by this provider.
Note this schema is only used by Studio to display a configuration form in case the provider is configured as a direct data source. The provider itself is responsible for validating the contents of its config. Assuming the provider uses Serde for parsing the config, validation is done at that stage.
This function only needs to be implemented by providers that are statically bundled with Studio. You should never have to implement it, it is mentioned here for the sake of completeness.
Imported functions
These functions are usable as long as you import fiberplane_pdk::prelude::*
in your library code. These functions allow you to access features provided to you by the runtime.
For the Fiberplane Daemon, these functions are implemented in the Provider Runtime crate.
make_http_request
make_http_request
Signature
pub async fn make_http_request(request: HttpRequest) -> Result<HttpResponse, HttpRequestError>;
Description
This is the most useful imported function, it allows the providers to make HTTP queries to remote hosts through the hosting runtime. A basic example of its usage can be seen in the tutorial to create a provider:
let base_url: Url = "https://jsonplaceholder.typicode.com".parse().unwrap();
let url = base_url
.join("/users")
.unwrap();
let request = HttpRequest::builder()
.method(HttpRequestMethod::Get)
.url(url.to_string())
.body(None)
.headers(None)
.build();
let response = make_http_request(request).await?;
serde_json::from_slice(&response.body).map_err(|e| Error::Deserialization { message: format!("Could not deserialize payload: {e:?}") })
log
log
Signature
pub fn log(message: String);
Description
This function asks the hosting runtime to log a message. This will make your log messages appear in Studio or in the standard output of the Fiberplane Daemon instance. Its usage is often as simple as:
let location = GeoLocation { latitude: 50.1234, longitude: 4.12084837 };
log(format!("Catnip: looking for the closest dispenser to {location:?} now..."));
random
random
Signature
pub fn random(len: u32) -> Vec<u8>;
Description
Query the hosting runtime for a source of randomness. Note that there is no guarantee that the random values you obtain this way to be cryptographically secure: it is entirely dependent on the runtime implementation. You can see the implementation of randomness for the Fiberplane Daemon in the Provider Runtime crate source code.
For example, you could create a getrandom provider using it
// In a helper crate like getrandom_fp_provider
use getrandom::Error;
pub fn use_fp_bindings(buf: &mut [u8]) -> Result<(), Error> {
let vals = random(buf.len());
buf.copy_from_slice(&vals);
Ok(())
}
// In your provider crate
use getrandom_fp_provider::use_fp_bindings;
use getrandom::register_custom_getrandom;
register_custom_getrandom!(use_fp_bindings);
Note: this example snippet might prove generic and useful enough to be upstreamed by Fiberplane and available as a public helper crate. Stay tuned!
now
now
Signature
pub fn now() -> Timestamp;
Description
Returns a timestamp of the current time of execution. The usefulness of this timestamp comes from what you want to do with timers, or signature creation/verification schemes.