Inhaltsverzeichnis
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:
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.