From 1d48460736aff03236ec739b1d7569b58529ee46 Mon Sep 17 00:00:00 2001 From: Thorsten Hans Date: Thu, 9 Jan 2025 17:16:33 +0100 Subject: [PATCH 1/4] chore: rework Spin trigger docs Signed-off-by: Thorsten Hans --- content/spin/v3/command-trigger.md | 114 +++++++++++++ content/spin/v3/community-kinesis-trigger.md | 131 ++++++++++++++ content/spin/v3/community-mqtt-trigger.md | 170 +++++++++++++++++++ content/spin/v3/cron-trigger.md | 146 ++++++++++++++++ content/spin/v3/http-trigger.md | 22 +++ content/spin/v3/redis-trigger.md | 22 +++ content/spin/v3/sqs-trigger.md | 41 +++++ content/spin/v3/triggers.md | 125 ++------------ templates/spin_sidebar_v3.hbs | 20 +++ 9 files changed, 684 insertions(+), 107 deletions(-) create mode 100644 content/spin/v3/command-trigger.md create mode 100644 content/spin/v3/community-kinesis-trigger.md create mode 100644 content/spin/v3/community-mqtt-trigger.md create mode 100644 content/spin/v3/cron-trigger.md create mode 100644 content/spin/v3/sqs-trigger.md diff --git a/content/spin/v3/command-trigger.md b/content/spin/v3/command-trigger.md new file mode 100644 index 000000000..b9d5cac36 --- /dev/null +++ b/content/spin/v3/command-trigger.md @@ -0,0 +1,114 @@ +title = "The Spin Command Trigger" +template = "spin_main" +date = "2025-01-09T00:00:01Z" +enable_shortcodes = true +[extra] +url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/command-trigger.md" + +--- + +- [Installing the Command Trigger](#installing-the-command-trigger) + - [Installing the Command Trigger Plugin](#installing-the-command-trigger-plugin) + - [Installing the Command Trigger Template](#installing-the-command-trigger-template) +- [Creating the Application](#creating-the-application) + - [Inspecting the Source Code](#inspecting-the-source-code) + - [Building and Running the Application](#building-and-running-the-application) +- [Learn more about the Spin Command Trigger](#learn-more-about-the-spin-command-trigger) +- [Additional Spin Triggers](#additional-spin-triggers) + - [Common Triggers](#common-triggers) + - [Community Triggers](#community-triggers) + + +Spin has experimental support for creating and running components once. Please note that there are only working Command Trigger app samples written in [Rust](https://github.com/fermyon/spin-trigger-command/tree/main/examples) at present. + +> Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `command` because non-HTTP triggers are not supported in Fermyon Cloud. + +Let's look at how the [experimental Command trigger for Spin](https://github.com/fermyon/spin-trigger-command/) allows you to deploy an application that runs once to completion. The Command trigger specification references a specific component. For example: + + + +```toml +[[trigger.command]] +component = "hello" +``` + +## Installing the Command Trigger + +### Installing the Command Trigger Plugin + +First, we install the plugin: + +```bash +spin plugins update +spin plugin install trigger-command +``` + +### Installing the Command Trigger Template + +Then, we install the template: + +```bash +spin templates install --git https://github.com/fermyon/spin-trigger-command +``` + +## Creating the Application + +With the plugin and template installed, we create a new application: + +```bash +spin new -t command-rust hello --accept-defaults +``` + +### Inspecting the Source Code + +The Rust source code for this application is as follows: + +```Rust +fn main() { + println!("Hello, Fermyon!"); +} +``` + +### Building and Running the Application + +We can immediately run this pre-written (template) application and observe the time-driven execution: + +```bash +cd hello +spin build --up + +Building component hello with `cargo build --target wasm32-wasi --release` + +... + +Finished building all Spin components + +Hello, Fermyon! +``` + +As we can see from the above output, our application is executed once to completion without the need for any incoming requests. + +## Learn more about the Spin Command Trigger + + + +If you would like to learn more about using the Spin Command Trigger, please check out the [Spin Command Trigger GitHub repository](https://github.com/fermyon/spin-trigger-command/). + +## Additional Spin Triggers + +You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin. + +### Common Triggers + +- [HTTP Trigger](./http-trigger.md) +- [Redis Trigger](./redis-trigger.md) +- [Command Trigger](./command-trigger.md) +- [Cron Trigger](./cron-trigger.md) +- [SQS Trigger](./sqs-trigger.md) + +### Community Triggers + +The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following, additional Spin triggers: + +- [Kinesis Trigger](./community-kinesis-trigger.md) +- [MQTT Trigger](./community-mqtt-trigger.md) \ No newline at end of file diff --git a/content/spin/v3/community-kinesis-trigger.md b/content/spin/v3/community-kinesis-trigger.md new file mode 100644 index 000000000..bb04ce801 --- /dev/null +++ b/content/spin/v3/community-kinesis-trigger.md @@ -0,0 +1,131 @@ +title = "The Spin Kinesis Trigger (Community)" +template = "spin_main" +date = "2025-01-09T00:00:01Z" +enable_shortcodes = true +[extra] +url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/community-kinesis-trigger.md" + +--- + +- [Installing the AWS Kinesis Trigger](#installing-the-aws-kinesis-trigger) + - [Installing the AWS Kinesis Trigger Plugin](#installing-the-aws-kinesis-trigger-plugin) + - [Installing the AWS Kinesis Trigger Template](#installing-the-aws-kinesis-trigger-template) +- [Creating the Application](#creating-the-application) + - [Inspecting the Source Code](#inspecting-the-source-code) +- [Building and Running the Application](#building-and-running-the-application) +- [Additional Spin Triggers](#additional-spin-triggers) + - [Common Triggers](#common-triggers) + - [Community Triggers](#community-triggers) + + +Spin has experimental support for creating and running components on real time data records streamed through [AWS Kinesis](https://docs.aws.amazon.com/streams/latest/dev/introduction.html). Please note that there are only working Kinesis Trigger app samples written in [Rust](https://github.com/ogghead/spin-trigger-kinesis). + +> Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `kinesis` because non-HTTP triggers are not supported in Fermyon Cloud. + +Let's look at how the [experimental Kinesis trigger for Spin](https://github.com/ogghead/spin-trigger-kinesis) allows you to deploy an application that runs based on real time data records streamed through AWS Kinesis. (Provisioning and configuring AWS Kinesis is out of scope for this article). The Kinesis trigger leverages AWS credentials from the standard AWS configuration environment variables and maps a AWS Kinesis stream to a specific component. For example: + + + +```toml +[[trigger.kinesis]] +stream_arn = "arn:aws:kinesis:us-east-1:1234567890:stream/TestStream" +batch_size = 1000 +shard_idle_wait_millis = 250 +detector_poll_millis = 30000 +shard_iterator_type = "TRIM_HORIZON" +component = "hello" +``` + +> Note: See [the list of all available configuration variables](https://github.com/ogghead/spin-trigger-kinesis?tab=readme-ov-file#spintoml) for the AWS Kinesis trigger. + +## Installing the AWS Kinesis Trigger + +### Installing the AWS Kinesis Trigger Plugin + +First, we install the plugin: + +```bash +spin plugins update +spin plugins install trigger-kinesis +``` + +### Installing the AWS Kinesis Trigger Template + +Then, we install the template: + +```bash +spin templates install --git https://github.com/ogghead/spin-trigger-kinesis +``` + +## Creating the Application + +With the plugin and template installed, we create a new application: + +```bash +spin new -t kinesis-rust hello --accept-defaults +``` + +As part of creating the new application, `spin` CLI will ask for the Amazon Resource Name (ARN). When asked, provide the ARN of your AWS Kinesis instance and confirm it with `[ENTER]`. + +### Inspecting the Source Code + +The Rust source code for this application is as follows: + +```Rust +use spin_kinesis_sdk::{kinesis_component, Error, KinesisRecord}; + +#[kinesis_component] +async fn handle_batch_records(records: Vec) -> Result<(), Error> { + for record in records { + println!("I GOT A RECORD! ID: {:?}", record.sequence_number); + let data = String::from_utf8(record.data.inner).unwrap(); + println!(" ... DATA: {:?}", data); + } + + Ok(()) +} + +``` + +## Building and Running the Application + +We can immediately run this pre-written (template) application and observe the time-driven execution: + +```bash +cd hello +spin build --up + +Building component hello with `cargo build --target wasm32-wasi --release` + +... + +Finished building all Spin components +Logging component stdio to ".spin/logs/" +I GOT A RECORD! ID: 101 + ... DATA: { "value" : "foo" } +I GOT A RECORD! ID: 102 + ... DATA: { "value" : "bar" } +``` + +As we can see from the above output, our application is now running and executing the function for each data record sent through your individual AWS Kinesis instance. + +If you would like to learn more about using the Spin Kinesis Trigger, please check out the ["How I wrote A Kinesis Trigger PLugin For Spin"](https://www.fermyon.com/blog/how-i-wrote-a-kinesis-trigger-plugin-for-spin) blog post and consult the [Spin Kinesis Trigger GitHub repository](https://github.com/ogghead/spin-trigger-kinesis/). + +## Additional Spin Triggers + +You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin. + +### Common Triggers + +- [HTTP Trigger](./http-trigger.md) +- [Redis Trigger](./redis-trigger.md) +- [Command Trigger](./command-trigger.md) +- [Cron Trigger](./cron-trigger.md) +- [SQS Trigger](./sqs-trigger.md) + +### Community Triggers + +The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following, additional Spin triggers: + +- [Kinesis Trigger](./community-kinesis-trigger.md) +- [MQTT Trigger](./community-mqtt-trigger.md) \ No newline at end of file diff --git a/content/spin/v3/community-mqtt-trigger.md b/content/spin/v3/community-mqtt-trigger.md new file mode 100644 index 000000000..66214a657 --- /dev/null +++ b/content/spin/v3/community-mqtt-trigger.md @@ -0,0 +1,170 @@ +title = "The Spin MQTT Trigger (Community)" +template = "spin_main" +date = "2025-01-09T00:00:01Z" +enable_shortcodes = true +[extra] +url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/community-mqtt-trigger.md" + +--- + +- [Installing the MQTT Trigger](#installing-the-mqtt-trigger) + - [Installing the MQTT Trigger Plugin](#installing-the-mqtt-trigger-plugin) + - [Installing the MQTT Trigger Template](#installing-the-mqtt-trigger-template) +- [Creating the Application](#creating-the-application) + - [Configuring the MQTT Connection](#configuring-the-mqtt-connection) + - [Inspecting the Source Code](#inspecting-the-source-code) +- [Building and Running the Application](#building-and-running-the-application) +- [Additional Spin Triggers](#additional-spin-triggers) + - [Common Triggers](#common-triggers) + - [Community Triggers](#community-triggers) + + +Spin has experimental support for creating and running components for MQTT messages. Please note that there are only working MQTT Trigger app samples written in [Rust](https://github.com/spinkube/spin-trigger-mqtt/tree/main/examples/mqtt-app) at present. + +> Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `mqtt` because non-HTTP triggers are not supported in Fermyon Cloud. + +Let's look at how the [experimental MQTT trigger for Spin](https://github.com/spinkube/spin-trigger-mqtt) allows you to deploy an application that runs for every message received via MQTT. A MQTT trigger maps a configurable MQTT service to a specific component. For example: + + + +```toml +[application.trigger.mqtt] +address = "mqtt://localhost:1883" +username = "user" +password = "password" +keep_alive_interval = "30" + +[[trigger.mqtt]] +id = "mqtt-01" +component = "hello" +topic = "topic-one" +qos = "1" +``` + +> Note: A single Spin App could consist of multiple MQTT triggers invoking different components for individual topics, as shown in the next snippet + +```toml +[application.trigger.mqtt] +address = "mqtt://localhost:1883" +username = "user" +password = "password" +keep_alive_interval = "30" + +[[trigger.mqtt]] +id = "mqtt-01" +component = "hello-one" +topic = "topic-one" +qos = "1" + +[[trigger.mqtt]] +id = "mqtt-02" +component = "hello-two" +topic = "topic-two" +qos = "1" +``` + +In the snippet above, you can see that different components are instantiated and invoked for messages appearing in topics `topic-one` and `topic-two`. + + +## Installing the MQTT Trigger + +### Installing the MQTT Trigger Plugin + +First, we install the plugin: + +```bash +spin plugin install --url https://github.com/spinkube/spin-trigger-mqtt/releases/download/canary/trigger-mqtt.json --yes +``` + +### Installing the MQTT Trigger Template + +Then, we install the template: + +```bash +spin templates install --git https://github.com/spinkube/spin-trigger-mqtt --upgrade +``` + +## Creating the Application + +With the plugin and template installed, we create a new application: + +```bash +spin new -t mqtt-rust hello --accept-defaults +``` + +As part of creating the new application, `spin` CLI will ask for the desired topic name. When asked, provide your topic name and confirm with `[ENTER]`. + +### Configuring the MQTT Connection + +The template will generate a Spin Application Manifest (`spin.toml`) for you. Configure the required settings under `[application.mqtt.trigger]` according to your needs. By default, the following configuration will be generated: + +```toml +[application.trigger.mqtt] +address = "mqtt://localhost:1883" +username = "" +password = "" +keep_alive_interval = "30" +``` + +### Inspecting the Source Code + +The Rust source code for this application is as follows: + +```Rust +use chrono::{DateTime, Utc}; +use spin_mqtt_sdk::{mqtt_component, Metadata, Payload}; + +#[mqtt_component] +async fn handle_message(message: Payload, metadata: Metadata) -> anyhow::Result<()> { + let datetime: DateTime = std::time::SystemTime::now().into(); + let formatted_time = datetime.format("%Y-%m-%d %H:%M:%S").to_string(); + + println!( + "{:?} Message received by wasm component: '{}'", + formatted_time, + String::from_utf8_lossy(&message) + ); + Ok(()) +} +``` + +## Building and Running the Application + +We can immediately run this pre-written (template) application and observe the execution: + +```bash +cd hello +spin build --up + +Building component hello with `cargo build --target wasm32-wasi --release` + +... + +Finished building all Spin components +2025-01-09 15:59:13 Message received by wasm component: 'Hello' +2025-01-09 15:59:14 Message received by wasm component: 'Fermyon' +2025-01-09 15:59:18 Message received by wasm component: 'Friends' +``` + +As we can see from the above output, our application is now running and executing the function every message appearing in the specified topic of the MQTT service. + +If you would like to learn more about using the Spin MQTT Trigger, please check out the [Spin MQTT Trigger GitHub repository](https://github.com/spinkube/spin-trigger-mqtt). + +## Additional Spin Triggers + +You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin. + +### Common Triggers + +- [HTTP Trigger](./http-trigger.md) +- [Redis Trigger](./redis-trigger.md) +- [Command Trigger](./command-trigger.md) +- [Cron Trigger](./cron-trigger.md) +- [SQS Trigger](./sqs-trigger.md) + +### Community Triggers + +The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following, additional Spin triggers: + +- [Kinesis Trigger](./community-kinesis-trigger.md) +- [MQTT Trigger](./community-mqtt-trigger.md) diff --git a/content/spin/v3/cron-trigger.md b/content/spin/v3/cron-trigger.md new file mode 100644 index 000000000..97d0265ce --- /dev/null +++ b/content/spin/v3/cron-trigger.md @@ -0,0 +1,146 @@ +title = "The Spin Cron Trigger" +template = "spin_main" +date = "2025-01-09T00:00:01Z" +enable_shortcodes = true +[extra] +url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/cron-trigger.md" + +--- + +- [Cron Trigger Expressions](#cron-trigger-expressions) +- [Installing the Cron Trigger](#installing-the-cron-trigger) + - [Installing the Cron Trigger Plugin](#installing-the-cron-trigger-plugin) + - [Installing the Cron Trigger Template](#installing-the-cron-trigger-template) +- [Creating the Application](#creating-the-application) + - [Inspecting the Source Code](#inspecting-the-source-code) +- [Building and Running the Application](#building-and-running-the-application) +- [Additional Spin Triggers](#additional-spin-triggers) + - [Common Triggers](#common-triggers) + - [Community Triggers](#community-triggers) + + +Spin has experimental support for creating and running components on a schedule. Please note that there are only working Cron Trigger app samples written in [Rust](https://github.com/fermyon/spin-trigger-cron/tree/main/guest-rust) and [Python](https://github.com/fermyon/spin-trigger-cron/tree/main/guest-python) at present. + +> Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `cron` because non-HTTP triggers are not supported in Fermyon Cloud. + +Let's look at how the [experimental Cron trigger for Spin](https://github.com/fermyon/spin-trigger-cron) allows you to deploy an application that runs on a schedule. A Cron trigger maps a cron expression (a schedule) to a specific component. For example: + + + +```toml +[[trigger.cron]] +component = "hello-cron" +cron_expression = "1/2 * * * * *" +``` + +> Note: The 7th field (year) for the `cron_expression` is optional. + +## Cron Trigger Expressions + +The expression is based on the crontab (cron table) syntax whereby each line is made up of 7 fields that represent the time to execute. + +```bash +# ┌──────────── sec (0–59) +# | ┌───────────── min (0–59) +# | │ ┌───────────── hour (0–23) +# | │ │ ┌───────────── day of month (1–31) +# | │ │ │ ┌───────────── month (1–12) +# | │ │ │ │ ┌───────────── day of week (0–6) +# | │ │ │ │ | ┌─────────────- year +# | │ │ │ │ | │ +# | │ │ │ │ | │ + 1/30 * * * * * * +``` + +> For more information about setting the schedule, please see the [Spin Cron Trigger repository](https://github.com/fermyon/spin-trigger-cron?tab=readme-ov-file#trigger-configuration). + +Let's look at a time-based workload inside a Rust application. + +## Installing the Cron Trigger + +### Installing the Cron Trigger Plugin + +First, we install the plugin: + +```bash +spin plugins install --url https://github.com/fermyon/spin-trigger-cron/releases/download/canary/trigger-cron.json +``` + +### Installing the Cron Trigger Template + +Then, we install the template: + +```bash +spin templates install --git https://github.com/fermyon/spin-trigger-cron +``` + +## Creating the Application + +With the plugin and template installed, we create a new application: + +```bash +spin new -t cron-rust hello_cron --accept-defaults +``` + +### Inspecting the Source Code + +The Rust source code for this application is as follows: + +```Rust +use spin_cron_sdk::{cron_component, Error, Metadata}; +use spin_sdk::variables; + +#[cron_component] +async fn handle_cron_event(metadata: Metadata) -> Result<(), Error> { + let key = variables::get("something").unwrap_or_default(); + println!( + "[{}] Hello this is me running every {}", + metadata.timestamp, key + ); + Ok(()) +} +``` + +## Building and Running the Application + +We can immediately run this pre-written (template) application and observe the time-driven execution: + +```bash +cd hello_cron +spin build --up + +Building component hello-cron with `cargo build --target wasm32-wasi --release` + +... + +Finished building all Spin components +[1715640447] Hello from a cron component +[1715640449] Hello from a cron component +[1715640451] Hello from a cron component +[1715640453] Hello from a cron component +[1715640455] Hello from a cron component +[1715640457] Hello from a cron component +``` + +As we can see from the above output, our application is now running and executing the function every two seconds without the need for any incoming requests or any intervention from users or other machines. + +If you would like to learn more about using the Spin Cron Trigger, please check out [the Spin Cron Trigger blog post](https://www.fermyon.com/blog/spin-cron-trigger) and the [Spin Cron Trigger GitHub repository](https://github.com/fermyon/spin-trigger-cron). + +## Additional Spin Triggers + +You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin. + +### Common Triggers + +- [HTTP Trigger](./http-trigger.md) +- [Redis Trigger](./redis-trigger.md) +- [Command Trigger](./command-trigger.md) +- [Cron Trigger](./cron-trigger.md) +- [SQS Trigger](./sqs-trigger.md) + +### Community Triggers + +The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following, additional Spin triggers: + +- [Kinesis Trigger](./community-kinesis-trigger.md) +- [MQTT Trigger](./community-mqtt-trigger.md) \ No newline at end of file diff --git a/content/spin/v3/http-trigger.md b/content/spin/v3/http-trigger.md index 0afc9cb3d..bd83d3f25 100644 --- a/content/spin/v3/http-trigger.md +++ b/content/spin/v3/http-trigger.md @@ -23,6 +23,9 @@ url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/http-trigg - [Exposing HTTP Triggers Using HTTPS](#exposing-http-triggers-using-https) - [Trigger Options](#trigger-options) - [Environment Variables](#environment-variables) +- [Additional Spin Triggers](#additional-spin-triggers) + - [Common Triggers](#common-triggers) + - [Community Triggers](#community-triggers) HTTP applications are an important workload in event-driven environments, and Spin has built-in support for creating and running HTTP @@ -511,3 +514,22 @@ Once set, `spin up` will automatically use these explicitly set environment vari export SPIN_TLS_CERT= export SPIN_TLS_KEY= ``` + +## Additional Spin Triggers + +You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin. + +### Common Triggers + +- [HTTP Trigger](./http-trigger.md) +- [Redis Trigger](./redis-trigger.md) +- [Command Trigger](./command-trigger.md) +- [Cron Trigger](./cron-trigger.md) +- [SQS Trigger](./sqs-trigger.md) + +### Community Triggers + +The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following, additional Spin triggers: + +- [Kinesis Trigger](./community-kinesis-trigger.md) +- [MQTT Trigger](./community-mqtt-trigger.md) \ No newline at end of file diff --git a/content/spin/v3/redis-trigger.md b/content/spin/v3/redis-trigger.md index c00ed0b2b..8a5f14422 100644 --- a/content/spin/v3/redis-trigger.md +++ b/content/spin/v3/redis-trigger.md @@ -12,6 +12,9 @@ url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/redis-trig - [Redis Components](#redis-components) - [The Message Handler](#the-message-handler) - [Inside Redis Components](#inside-redis-components) +- [Additional Spin Triggers](#additional-spin-triggers) + - [Common Triggers](#common-triggers) + - [Community Triggers](#community-triggers) Pub-sub (publish-subscribe) messaging is a popular architecture for asynchronous message processing. Spin has built-in support to creating and running applications in response to messages on [pub-sub Redis channels](https://redis.io/topics/pubsub). @@ -167,3 +170,22 @@ interface inbound-redis { This is the interface that all Redis components must implement, and which is used by Spin when instantiating and invoking the component. However, it is implemented internally by the Spin SDK - you don't need to implement it directly. + +## Additional Spin Triggers + +You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin. + +### Common Triggers + +- [HTTP Trigger](./http-trigger.md) +- [Redis Trigger](./redis-trigger.md) +- [Command Trigger](./command-trigger.md) +- [Cron Trigger](./cron-trigger.md) +- [SQS Trigger](./sqs-trigger.md) + +### Community Triggers + +The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following, additional Spin triggers: + +- [Kinesis Trigger](./community-kinesis-trigger.md) +- [MQTT Trigger](./community-mqtt-trigger.md) \ No newline at end of file diff --git a/content/spin/v3/sqs-trigger.md b/content/spin/v3/sqs-trigger.md new file mode 100644 index 000000000..89416b477 --- /dev/null +++ b/content/spin/v3/sqs-trigger.md @@ -0,0 +1,41 @@ +title = "The Spin SQS Trigger" +template = "spin_main" +date = "2023-11-04T00:00:01Z" +enable_shortcodes = true +[extra] +url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/sqs-trigger.md" + +--- + +- [Installing the AWS Kinesis Trigger](#installing-the-aws-kinesis-trigger) + - [Installing the AWS Kinesis Trigger Plugin](#installing-the-aws-kinesis-trigger-plugin) + - [Installing the AWS Kinesis Trigger Template](#installing-the-aws-kinesis-trigger-template) +- [Creating the Application](#creating-the-application) + - [Inspecting the Source Code](#inspecting-the-source-code) +- [Building and Running the Application](#building-and-running-the-application) + + +Spin has experimental support for creating and running components for messages appearing in [Amazon Simple Queue Service (SQS)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html) queues. Please note that there are only working Kinesis Trigger app samples written in [Rust](https://github.com/ogghead/spin-trigger-kinesis). + +> Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `sqs` because non-HTTP triggers are not supported in Fermyon Cloud. + +TBD + +## Additional Spin Triggers + +You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin. + +### Common Triggers + +- [HTTP Trigger](./http-trigger.md) +- [Redis Trigger](./redis-trigger.md) +- [Command Trigger](./command-trigger.md) +- [Cron Trigger](./cron-trigger.md) +- [SQS Trigger](./sqs-trigger.md) + +### Community Triggers + +The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following, additional Spin triggers: + +- [Kinesis Trigger](./community-kinesis-trigger.md) +- [MQTT Trigger](./community-mqtt-trigger.md) \ No newline at end of file diff --git a/content/spin/v3/triggers.md b/content/spin/v3/triggers.md index c391e3933..ebe6bb4a4 100644 --- a/content/spin/v3/triggers.md +++ b/content/spin/v3/triggers.md @@ -11,13 +11,9 @@ url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/triggers.m - [Writing the Component Inside the Trigger](#writing-the-component-inside-the-trigger) - [Choosing Between the Approaches](#choosing-between-the-approaches) - [Setting Up Multiple Trigger Types](#setting-up-multiple-trigger-types) -- [Spin Cron Trigger](#spin-cron-trigger) - - [Cron Trigger Expressions](#cron-trigger-expressions) - - [Installing the Cron Trigger Plugin](#installing-the-cron-trigger-plugin) - - [Installing the Cron Trigger Template](#installing-the-cron-trigger-template) - - [Creating the Web Application](#creating-the-web-application) - - [Inspecting the Source Code](#inspecting-the-source-code) - - [Building and Running the Application](#building-and-running-the-application) +- [Available Triggers for Spin](#available-triggers-for-spin) + - [Common Triggers](#common-triggers) + - [Community Triggers](#community-triggers) A Spin _trigger_ maps an event, such as an HTTP request or a Redis pub-sub message, to a component that handles that event. @@ -102,12 +98,15 @@ Here is an example of creating an application with both HTTP and Redis triggers: # Start with an empty application $ spin new -t http-empty multiple-trigger-example Description: An application that handles both HTTP requests and Redis messages + # Change into to the application directory $ cd multiple-trigger-example + # Add an HTTP trigger application $ spin add -t http-rust rust-http-trigger-example Description: A Rust HTTP example HTTP path: /... + # Add a Redis trigger application $ spin add -t redis-rust rust-redis-trigger-example Description: A Rust redis example @@ -156,109 +155,21 @@ workdir = "rust-redis-trigger-example" watch = ["src/**/*.rs", "Cargo.toml"] ``` -## Cron Trigger - -Spin has experimental support for creating and running components on a schedule. Please note that there are only working Cron Trigger app samples written in [Rust](https://github.com/fermyon/spin-trigger-cron/tree/main/guest-rust) and [Python](https://github.com/fermyon/spin-trigger-cron/tree/main/guest-python) at present. - -> Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `cron` because non-HTTP triggers are not supported in Fermyon Cloud. - -Let's look at how the [experimental Cron trigger for Spin](https://github.com/fermyon/spin-trigger-cron) allows you to deploy an application that runs on a schedule. A Cron trigger maps a cron expression (a schedule) to a specific component. For example: - - - -```toml -[[trigger.cron]] -component = "hello-cron" -cron_expression = "1/2 * * * * *" -``` - -> Note: The 7th field (year) for the `cron_expression` is optional. - -### Cron Trigger Expressions - -The expression is based on the crontab (cron table) syntax whereby each line is made up of 7 fields that represent the time to execute. - -```bash -# ┌──────────── sec (0–59) -# | ┌───────────── min (0–59) -# | │ ┌───────────── hour (0–23) -# | │ │ ┌───────────── day of month (1–31) -# | │ │ │ ┌───────────── month (1–12) -# | │ │ │ │ ┌───────────── day of week (0–6) -# | │ │ │ │ | ┌─────────────- year -# | │ │ │ │ | │ -# | │ │ │ │ | │ - 1/30 * * * * * * -``` +## Available Triggers for Spin -> For more information about setting the schedule, please see the [Spin Cron Trigger repository](https://github.com/fermyon/spin-trigger-cron?tab=readme-ov-file#trigger-configuration). +You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin. -Let's look at a time-based workload inside a Rust application. - -### Installing the Cron Trigger Plugin - -First, we install the plugin: - -```bash -spin plugins install --url https://github.com/fermyon/spin-trigger-cron/releases/download/canary/trigger-cron.json -``` +### Common Triggers -### Installing the Cron Trigger Template +- [HTTP Trigger](./http-trigger.md) +- [Redis Trigger](./redis-trigger.md) +- [Command Trigger](./command-trigger.md) +- [Cron Trigger](./cron-trigger.md) +- [SQS Trigger](./sqs-trigger.md) -Then, we install the template: - -```bash -spin templates install --git https://github.com/fermyon/spin-trigger-cron -``` - -### Creating the Application - -With the plugin and template installed, we create a new application: - -```bash -spin new -t cron-rust hello_cron --accept-defaults -``` - -### Inspecting the Source Code - -The Rust source code for this application is as follows: - -```Rust -use spin_cron_sdk::{cron_component, Error, Metadata}; -use spin_sdk::variables; - -#[cron_component] -async fn handle_cron_event(metadata: Metadata) -> Result<(), Error> { - let key = variables::get("something").unwrap_or_default(); - println!( - "[{}] Hello this is me running every {}", - metadata.timestamp, key - ); - Ok(()) -} -``` - -### Building and Running the Application - -We can immediately run this pre-written (template) application and observe the time-driven execution: - -```bash -cd hello_cron -spin build --up - -Building component hello-cron with `cargo build --target wasm32-wasip1 --release` - -... - -Finished building all Spin components -[1715640447] Hello from a cron component -[1715640449] Hello from a cron component -[1715640451] Hello from a cron component -[1715640453] Hello from a cron component -[1715640455] Hello from a cron component -[1715640457] Hello from a cron component -``` +### Community Triggers -As we can see from the above output, our application is now running and executing the function every two seconds without the need for any incoming requests or any intervention from users or other machines. +The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following, additional Spin triggers: -If you would like to learn more about using the Spin Cron Trigger, please check out [the Spin Cron Trigger blog post](https://www.fermyon.com/blog/spin-cron-trigger) and the [Spin Cron Trigger GitHub repository](https://github.com/fermyon/spin-trigger-cron). +- [Kinesis Trigger](./community-kinesis-trigger.md) +- [MQTT Trigger](./community-mqtt-trigger.md) \ No newline at end of file diff --git a/templates/spin_sidebar_v3.hbs b/templates/spin_sidebar_v3.hbs index e5401ae8f..eaf3be2b4 100644 --- a/templates/spin_sidebar_v3.hbs +++ b/templates/spin_sidebar_v3.hbs @@ -111,6 +111,26 @@ {{/if}} href="{{site.info.base_url}}/spin/v3/redis-trigger">The Redis Trigger +
  • The Command + Trigger +
    • +
  • The Cron + Trigger +
    • +
  • The SQS + Trigger +
    • +
  • The MQTT + Trigger +
    • +
  • The Kinesis + Trigger +
    • From 88967be3ba1346b4c379b8aa61056e6deed8027f Mon Sep 17 00:00:00 2001 From: Thorsten Hans Date: Thu, 9 Jan 2025 22:06:18 +0100 Subject: [PATCH 2/4] Update content/spin/v3/command-trigger.md Co-authored-by: itowlson Signed-off-by: Thorsten Hans --- content/spin/v3/command-trigger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/spin/v3/command-trigger.md b/content/spin/v3/command-trigger.md index b9d5cac36..8600d957c 100644 --- a/content/spin/v3/command-trigger.md +++ b/content/spin/v3/command-trigger.md @@ -19,7 +19,7 @@ url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/command-tr - [Community Triggers](#community-triggers) -Spin has experimental support for creating and running components once. Please note that there are only working Command Trigger app samples written in [Rust](https://github.com/fermyon/spin-trigger-command/tree/main/examples) at present. +Spin has experimental support for creating and running components once. Please note that there are only working Command trigger app samples written in [Rust](https://github.com/fermyon/spin-trigger-command/tree/main/examples) at present. > Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `command` because non-HTTP triggers are not supported in Fermyon Cloud. From 887f8f098f3c1eb7fba07134833bb3f6cc9dad7c Mon Sep 17 00:00:00 2001 From: Thorsten Hans Date: Thu, 9 Jan 2025 22:09:12 +0100 Subject: [PATCH 3/4] Update content/spin/v3/community-kinesis-trigger.md Co-authored-by: itowlson Signed-off-by: Thorsten Hans --- content/spin/v3/community-kinesis-trigger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/spin/v3/community-kinesis-trigger.md b/content/spin/v3/community-kinesis-trigger.md index bb04ce801..b196dc3f4 100644 --- a/content/spin/v3/community-kinesis-trigger.md +++ b/content/spin/v3/community-kinesis-trigger.md @@ -109,7 +109,7 @@ I GOT A RECORD! ID: 102 As we can see from the above output, our application is now running and executing the function for each data record sent through your individual AWS Kinesis instance. -If you would like to learn more about using the Spin Kinesis Trigger, please check out the ["How I wrote A Kinesis Trigger PLugin For Spin"](https://www.fermyon.com/blog/how-i-wrote-a-kinesis-trigger-plugin-for-spin) blog post and consult the [Spin Kinesis Trigger GitHub repository](https://github.com/ogghead/spin-trigger-kinesis/). +If you would like to learn more about using the Spin Kinesis trigger, please check out the ["How I wrote A Kinesis Trigger Plugin For Spin"](https://www.fermyon.com/blog/how-i-wrote-a-kinesis-trigger-plugin-for-spin) blog post and consult the [Kinesis trigger GitHub repository](https://github.com/ogghead/spin-trigger-kinesis/). ## Additional Spin Triggers From 453e9a3f1ebbc6749a8b613d6a5f532f2b556f07 Mon Sep 17 00:00:00 2001 From: Thorsten Hans Date: Thu, 9 Jan 2025 22:10:44 +0100 Subject: [PATCH 4/4] Update content/spin/v3/triggers.md Co-authored-by: itowlson Signed-off-by: Thorsten Hans --- content/spin/v3/triggers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/spin/v3/triggers.md b/content/spin/v3/triggers.md index ebe6bb4a4..52a3c56a5 100644 --- a/content/spin/v3/triggers.md +++ b/content/spin/v3/triggers.md @@ -169,7 +169,7 @@ You can leverage different triggers as part of your Spin apps to address common ### Community Triggers -The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following, additional Spin triggers: +The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following additional Spin triggers: - [Kinesis Trigger](./community-kinesis-trigger.md) - [MQTT Trigger](./community-mqtt-trigger.md) \ No newline at end of file