AfRA Matrix Bot

Overview

The AfRA Matrix Bot automatically sends notifications about the opening status of the AfRA Hackerspace to AfRA General Matrix chat.

The bot uses the public AfRA SpaceAPI as its source of truth and runs on Cloudflare Workers.

A Cloudflare Cron Trigger checks the current opening status 1x minute. A Durable Object stores the previously processed status to prevent repeated notifications when the status has not changed.

No additional server, Docker container, Home Assistant webhook, or Matrix homeserver administrator access is required.

The Worker also provides an authenticated endpoint for sending custom text messages.

Architecture Overview

AfRA SpaceAPI
https://spaceapi.afra-berlin.eu/
          |
          | HTTPS GET
          | 1x minute
          v
Cloudflare Worker
afra-bot
          |
          | Compare status
          v
Cloudflare Durable Object
SPACE_STATUS
          |
          | Only on status change
          v
Matrix Client-Server API
          |
          v
AfRA General Matrix Room

The Matrix access token and custom message API key are stored as Cloudflare Secrets.

No Matrix credentials are stored in Home Assistant or the public AfRA infrastructure repository.

SpaceAPI

The opening status is publicly available at:

AfRA SpaceAPI

The endpoint returns JSON containing the current opening status.

Example response (abbreviated):

{
  "api": "0.13",
  "space": "AfRA Berlin",
  "state": {
    "open": false,
    "lastchange": 1791578498.467487
  }
}

The field state.open indicates whether the Hackerspace is open.

Value Meaning
true is open
false is closed

The field state.lastchange contains the timestamp of the last reported status change.

Automatic Notifications

Cron Trigger

The Cloudflare Worker checks the SpaceAPI automatically 1x minute.

Cron expression:

*/1 * * * *

The Cron Trigger invokes the Worker's scheduled() handler.

Status Detection

The Worker retrieves the current status from:

https://spaceapi.afra-berlin.eu/

It compares the value of state.open with the previously stored status.

Previous Status Current Status Action
Unknown Closed Store initial status, no notification
Unknown Open Store initial status, no notification
Closed Closed No action
Closed Open Send opening notification
Open Open No action
Open Closed Send closing notification

Opening Notification

When the space opens, the bot sends:

🟢 🟢 🟢 AfRA Space is OPEN now! Come hack with us! 🚀

Closing Notification

When the space closes, the bot sends:

"\u{1F534} \u{1F534} \u{1F534} AfRA Space is CLOSED. See you next time, Bye Bye! \u{1F44B} "

Persistent State

The Worker uses a Cloudflare Durable Object to store the last processed opening status.

Setting Value
Durable Object class SpaceStatus
Binding SPACE_STATUS
Object identifier afra-space
Storage SQLite-backed Durable Object storage

The Durable Object coordinates status checks so that overlapping executions do not independently process the same status transition.

On its first successful execution, it stores the current status without sending a Matrix notification.

When a status change is detected, the Worker sends the Matrix notification and then stores the new status.

Note: The implementation does not guarantee exactly-once delivery if a process fails after Matrix accepts a message but before the updated status is stored.

Matrix Bot

A dedicated Matrix account named afra-bot was created by @rootcat for automated notifications.

The bot has joined the AfRA Matrix room.

Configuration

Setting Value
Bot afra-bot
Matrix homeserver https://matrix-client.matrix.org
Room ID !rCzxAMRXJsfoRsQknQ:ontheblueplanet.com
Room encryption Disabled

The bot account uses the matrix.org homeserver, while the Matrix room belongs to ontheblueplanet.com. !?!?! WTF

It works because Matrix supports federation between different homeservers.

Authentication

The bot uses a Matrix access token obtained through Element:

Settings → Help & About → Advanced → Access Token

The token is stored as a Cloudflare Secret named MATRIX_TOKEN lives 12h need to be renewed…

Cloudflare Worker

Worker Information

Setting Value
Worker name afra-bot
Runtime Cloudflare Workers
Configuration wrangler.jsonc
Source code src/index.js
Cron schedule */1 * * * *
Durable Object binding SPACE_STATUS
Rate limiter binding STATUS_LIMITER

Secrets

The following variables are configured as Cloudflare Secrets:

Variable Type Description
MATRIX_TOKEN Secret Matrix bot access token
MATRIX_ROOM_ID Secret Target Matrix room ID
BOT_API_KEY Secret Authentication key for custom messages

Rate Limiting

The Worker uses a Cloudflare Rate Limiting binding named STATUS_LIMITER.

Configured limit:

2 requests per 60 seconds

The rate limiter is used for the custom message endpoint.

Automatic SpaceAPI checks are not subject to this HTTP API rate limit.

Rate limiting reduces abuse, does not replace authentication.

Custom Messages

In addition to automatic status notifications, the Worker supports sending custom text messages.

Endpoint

POST /message

The endpoint requires an API key.

Authentication

Requests must include:

Authorization: Bearer <BOT_API_KEY>

The API key is stored as a Cloudflare Secret named BOT_API_KEY.

It is separate from the Matrix access token.

Requests without a valid API key return HTTP 401 Unauthorized.

Request Format

The endpoint accepts JSON:

{
  "message": "Hello AfRA!"
}

The message must be a non-empty string.

Maximum message length: 1000 characters.

Maximum request body size: 4096 bytes.

Send a message:

curl -X POST \
  "https://afra-bot.inthecloud.workers.dev/message" \
  -H "Authorization: Bearer $BOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello AfRA!"}'

Expected response:

OK: /message

Status: Endpoint implemented; end-to-end testing pending.

API Endpoints

Method Endpoint Authentication Function
POST /message API key Send a custom text message

Opening and closing notifications are generated automatically from the SpaceAPI.

The previous publicly accessible status endpoints have been disabled to prevent(@Yureka) arbitrary status notifications.

Deployment

The Worker is deployed using Cloudflare Wrangler.

Requirements

  • Node.js and npm
  • Cloudflare account access
  • Wrangler CLI

Authenticate with Cloudflare:

npx wrangler login

Deployment Commands

Validate the Worker locally:

npx wrangler deploy --dry-run

Deploy the Worker:

npx wrangler deploy

The deployment registers the Durable Object binding and Cron Trigger.

Home Assistant Integration

AfRA uses Home Assistant Core on NixOS.

The Home Assistant configuration is maintained in the public infrastructure repository:

AfRA Home Assistant Configuration

The SpaceAPI already exposes the opening status.

The Matrix Bot retrieves the status directly from the public SpaceAPI endpoint.

Therefore:

  • No additional Home Assistant REST commands are required.
  • No additional Home Assistant automations are required.
  • No webhook is required.
  • No Matrix credentials are stored in Home Assistant.
  • No API keys are required in the public infrastructure repository.

Security

Implemented Measures

  • Dedicated Matrix bot account
  • Matrix access token stored as a Cloudflare Secret
  • Custom message endpoint protected by a separate API key
  • No Matrix credentials in the public infrastructure repository
  • No Home Assistant webhook required
  • Public status-changing endpoints disabled
  • Only predefined automatic status notifications
  • Custom messages limited to 1000 characters
  • Custom message request bodies limited to 4096 bytes
  • Cloudflare rate limiting for custom messages
  • Persistent status tracking with a Durable Object

Known Limitations

The SpaceAPI is checked once per minute.

Temporary SpaceAPI or Matrix errors can delay notifications.

If the SpaceAPI changes state multiple times between checks, intermediate transitions may not be observed.

The Durable Object coordinates status processing, but the current implementation does not guarantee exactly-once Matrix delivery in every failure scenario.

The custom message endpoint requires a valid API key. Anyone possessing this key can send messages as the bot, so the key must be handled securely.

Testing

SpaceAPI

The public SpaceAPI was tested successfully:

curl -i https://spaceapi.afra-berlin.eu/

The response contained:

{
  "state": {
    "open": false
  }
}

Scheduled Execution

The Cloudflare Cron Trigger is configured to run every minute.

Manual scheduled execution was tested successfully.

Observed log output:

Scheduled check: {"status":"initialized","open":false}
Scheduled check: {"status":"unchanged","open":false}

Automatic Cron execution was subsequently confirmed.

Custom Messages

The custom message endpoint is implemented.

Authentication and Matrix delivery still require end-to-end testing.

Project Status

  • [x] Create Matrix bot account
  • [x] Invite bot to Matrix room
  • [x] Configure Matrix access token
  • [x] Create Cloudflare Worker
  • [x] Configure Matrix API
  • [x] Test manual opening notification
  • [x] Test manual closing notification
  • [x] Configure rate limiting
  • [x] Identify public SpaceAPI endpoint
  • [x] Implement automatic SpaceAPI polling
  • [x] Configure Durable Object
  • [x] Deploy updated Worker
  • [x] Configure Cron Trigger
  • [x] Verify scheduled execution
  • [x] Disable public status endpoints in Worker code
  • [x] Implement authenticated custom message endpoint
  • [x] Verify custom message API key configuration
  • [x] Test custom message endpoint
  • [x] Verify disabled status endpoints over HTTP
  • [x] Test real Space Open notification
  • [x] Test real Space Closed notification

References


Last updated: 2026-10-10

Status: Automatic SpaceAPI polling, Durable Object storage, and Cloudflare Cron Trigger, Custom message and real status-transition are operational.

Drucken/exportieren