smokesignal.events / showcase
A Rust application to showcase badge awards in the AT Protocol ecosystem.
fork atom
Rust 80.9%
Shell 14.6%
HTML 1.9%
PLpgSQL 1.6%
Dockerfile 0.9%
Other 0.1%
4 1 1

Clone this repository

https://tangled.org/smokesignal.events/showcase
git@tangled.org:smokesignal.events/showcase

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
README.md

Showcase#

A Rust crate for badge awards showcase functionality in the AT Protocol ecosystem.

Crate Overview#

The showcase crate provides a complete badge awards tracking and display system for AT Protocol communities. It offers both a library API and a standalone server application for processing, validating, and showcasing badge awards in real-time.

Core Functionality#

  • Real-time Event Processing: Consumes Jetstream events for community.lexicon.badge.award records
  • Cryptographic Validation: Verifies badge issuer signatures using AT Protocol identity resolution
  • Multi-Database Support: Works with both SQLite and PostgreSQL backends
  • Image Processing: Downloads, validates, and processes badge images (512x512 PNG format)
  • Web Interface: Provides REST API and HTML pages for displaying badge awards
  • File Storage: Supports local filesystem and S3-compatible object storage

Binaries#

showcase#

The main server application that runs a complete badge awards showcase system.

Purpose: Operates as a web server that consumes AT Protocol Jetstream events, validates badge awards, processes badge images, and serves a web interface for viewing awards.

Key Features:

  • Jetstream consumer with automatic reconnection and cursor persistence
  • HTTP server with template-rendered pages and REST API endpoints
  • Background badge processing with signature validation
  • Configurable via environment variables
  • Graceful shutdown handling

Usage:

cargo run --bin showcase

The server starts on the configured HTTP port (default: 8080) and begins consuming Jetstream events immediately.

Features#

  • Jetstream Consumer: Real-time processing of badge award events
  • Signature Validation: Verifies badge issuer signatures against configured issuers
  • Web Interface: Clean, responsive UI using Pico CSS
  • Badge Images: Downloads and processes badge images
  • Database Storage: SQLite database with efficient indexing

Architecture#

The application is structured into several modules:

  • src/config.rs - Configuration management with environment variables
  • src/storage.rs - Database operations and data models
  • src/http.rs - Web server and HTTP handlers
  • src/consumer.rs - Jetstream consumer and badge processing
  • src/lib.rs - Main application entry point

Configuration#

Configure the application using environment variables:

HTTP Server#

  • HTTP_PORT (default: 8080) - HTTP server port
  • HTTP_STATIC_PATH (default: ${CARGO_MANIFEST_DIR}/static) - Static files path
  • HTTP_TEMPLATES_PATH (default: ${CARGO_MANIFEST_DIR}/templates) - Templates path
  • EXTERNAL_BASE - External hostname of the site

AT Protocol#

  • PLC_HOSTNAME (default: plc.directory) - PLC server hostname
  • DNS_NAMESERVERS - DNS nameservers for handle resolution
  • USER_AGENT (default: auto-generated) - HTTP client user agent

Security#

  • CERTIFICATE_BUNDLES - CA certificate file paths (semicolon-separated)
  • HTTP_CLIENT_TIMEOUT (default: 10s) - HTTP client timeout
  • BADGE_ISSUERS - Trusted badge issuer DIDs (semicolon-separated)

Storage#

  • DATABASE_URL (default: sqlite://showcase.db) - Database connection string
  • BADGE_IMAGE_STORAGE (default: ./badges) - Badge image storage directory

Jetstream#

  • JETSTREAM_CURSOR_PATH - Optional path to cursor file for resuming Jetstream consumption

Quick Start#

  1. Install dependencies:

    cargo build

  2. Set required environment variables:

    export EXTERNAL_BASE=example.com
export BADGE_ISSUERS="did:plc:example1;did:plc:example2"

  3. Run the application:

    cargo run --bin showcase

  4. Visit the web interface: Open http://localhost:8080 in your browser

Development#

Build Commands#

  • cargo build - Build the project
  • cargo test - Run tests
  • cargo run --bin showcase - Run the application
  • cargo check - Check code without building
  • cargo fmt - Format code
  • cargo clippy - Lint code

Database#

The application uses SQLite with automatic migrations. The database schema includes:

  • identities - DID documents and handle mappings
  • awards - Badge award records with validation status
  • badges - Badge definitions and metadata

Templates#

HTML templates are located in the templates/ directory:

  • base.html - Base template with common layout
  • index.html - Home page showing recent awards
  • identity.html - Individual identity badge awards

Static Files#

CSS and other static assets are in the static/ directory:

  • pico.css - Main CSS framework
  • pico.colors.css - Color utilities
  • badges/ - Downloaded badge images

Badge Processing#

When badge awards are received via Jetstream:

  1. Badge definition is fetched and stored
  2. Badge image is downloaded and processed (512x512 PNG)
  3. Signatures are validated against configured issuers
  4. Award record is stored in database
  5. Badge count is updated
  6. Old awards are trimmed (max 100 per identity)

Jetstream Cursor Support#

The application supports resuming Jetstream consumption from a specific cursor position:

  • Set JETSTREAM_CURSOR_PATH to a file path (e.g., /tmp/jetstream_cursor)
  • On startup, if the file exists and contains a valid cursor value > 1, it will be used
  • The cursor (time_us value) is automatically written to the file every 30 seconds
  • This allows the application to resume processing from where it left off after restarts

API Endpoints#

  • GET / - Home page with recent awards
  • GET /badges/:subject - Identity page (accepts DID or handle)
  • GET /static/* - Static file serving

License#

Showcase is open source software released under the MIT License.