Integrations

Integrations allow you to build connected systems around Basalt. Basalt supports two first-party integrations out of the box. These are:

• Event Handlers
• Webhooks

Both of these systems allow you to process Basalt server events but in quite different ways.

Event Handlers

The integrations.event_handlers parameter within a configuration allows you to provide a path or list of paths to JavaScript or TypeScript files containing functions responsible for handling server events.

This allows you to hook into the Basalt system and run arbitrary code at runtime.

Consider an example. Let’s say we want to run some arbitrary JavaScript code each time a user checks in for the first time. This could be as simple as simply sending the event somewhere else or as complex as modifying server state.

basalt.toml

[integrations]
event_handlers = "./myHandler.js"
# or for multiple files
event_handlers = [ "./myHandler.js", "myOtherHandler.js" ]

myHandler.js

export const onCheckIn = async (event) => {
  console.log(event);
  console.log(event.kind);
  console.log(event.name);

  const result = await fetch("http://localhost:8081/", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: `Team ${event.name} just checked in`,
    }),
  });
  console.log(result.status);
  console.log(await result.text());
 };

This provided JavaScript code is executed by an embedded JavaScript runtime powered by Deno. If you’re not using this feature, the Basalt CLI will intelligently use a build of the server that does not compile with this feature enabled to save resources.

Webhooks

If all you want to do is forward events to some external service for them to be handled elsewhere, webhooks are likely what you want.

basalt.toml

[integrations]
webhooks = "http://localhost:8081/events"
# or for multiple recipients
# webhooks = [ "http://localhost:8081/events", "http://localhost:8082/events" ]

Server Events

The snippet below contains the definitions of all of Basalt’s server events. When an event is emitted, the pieces of data associated with each of these events is provided to any handlers hooked into Basalt.

events.rs

#[serde(tag = "kind")]
pub enum ServerEvent {
    #[serde(rename_all = "camelCase")]
    OnComplete { id: UserId, time: DateTime<Utc> },
    #[serde(rename_all = "camelCase")]
    OnPause {
        paused_by: UserId,
        time: DateTime<Utc>,
    },
    #[serde(rename_all = "camelCase")]
    OnUnpause {
        unpaused_by: UserId,
        time: DateTime<Utc>,
    },
    #[serde(rename_all = "camelCase")]
    OnTestEvaluation {
        id: UserId,
        question_idx: u32,
        question_text: String,
        test_results: TestResults,
        time: DateTime<Utc>,
    },
    #[serde(rename_all = "camelCase")]
    OnSubmissionEvaluation {
        id: UserId,
        question_idx: u32,
        question_text: String,
        test_results: TestResults,
        time: DateTime<Utc>,
    },
    #[serde(rename_all = "camelCase")]
    // Unused
    OnTeamKick {
        team_kicked: UserId,
        kicked_by: UserId,
        time: DateTime<Utc>,
    },
    #[serde(rename_all = "camelCase")]
    // Unused
    OnTeamBan {
        team_banned: UserId,
        banned_by: UserId,
        time: DateTime<Utc>,
    },
    #[serde(rename_all = "camelCase")]
    OnAnnouncement {
        announcer: UserId,
        announcement: String,
        time: DateTime<Utc>,
    },
    #[serde(rename_all = "camelCase")]
    OnCheckIn { id: UserId, time: DateTime<Utc> },
}

Source