README
¶
Emissary is the Social Web Toolkit -- a standalone Fediverse server designed for end users, app creators, and hosting admins — that gives everyone powerful new ways to join the social web.
Why Emissary?
Trustworthy Custom Applications
As a developer, Emissary empowers you to build custom, social applications in a simple, declarative, low-code environment. Using only HTML templates and a JSON config file, you can create full-featured social apps that are easy to deploy and easy to maintain.
This is done by building action pipelines out of simple, composable steps, like: "show an edit form", "create a thumbnail", and "save the object". Pipelines work alongside Emissary's built-in state machines and access permissions to form robust and secure applications that you and your end-users can trust.
Distribute your applications via Git and .zip files, comprising one or more Each template is isolated from others, so bugs in one template won't bleed out into the rest of your site. This should prevent the incompatibility, feature bloat, and bugginess that have plagued other plugin ecosystems.
Multi-Network
Emissary use the sherlock library to bridge across different federated protocols. This includes ActivityPub, RSS+WebSub, and IndieWeb. More are coming, to be added into the core system. This means that applications you build on Emissary interact with the entire social web, and will grow as Emissary grows.
Baked-In DevOps
Anyone should be able to stand up their own Emissary server. But few people will. Grandma probably won't. For Emissary to be successful, hosting companies must be able to offer new Emissary accounts at the click of a button.
This means that Emissary must be an exemplary citizen in any DevOps workflow. It should be as easy for an individual hobbyist to turn on a test server on a big hosting provider as it is for that big hosting provider to offer hundreds of thousands (or millions) of accounts to the general public at scale.
High Performance
Emissary is built to be fast on any hardware. Lightweight, cacheable templates work with the latest web performance techniques from htmx.org for a web application that always loads quickly and runs smoothly.
Get Started
To get started, visit the Emissary Developer Website. This resource is growing every day, and includes a quickstart guide along with detailed documentation on how to configure Emissary for your own environment.
Feature Checklist
There's a lot of work to do. Check out the project status page and the Emissary kanban for a peek at where we are right now.
Tech Stack
Emissary is intended to be as easy to run and as scalable as possible. It runs with a minimal set of dependencies, so you should be able to install and run an Emissary server in between lunch and tea time.
- Go
- Mongodb
- HTMX / Hyperscript
- That's it. I'll worry about a cute acronym later.
Emissary also relies on a stack of custom libraries that make it go:
- Hannibal - A robust, idiomatic ActivityPub interfaces in Go
- Sherlock - Inspect data in ActivityPub/RSS/MicroFormats and more
- Toot - Mastodon Server API
- Rosetta - Data mapping and manipulations: schemas, conversions, etc
A complete list can be found in the Go module file.
Everyone Welcome
I welcome your thoughts, ideas, feedback, criticisms, and mockery if it will help create a more realistic and workable way for people to use the Internet as originally intended.
Please try it out, get in touch, file a suggestion, report bugs "@" me, block me, whatever. Just get involved and help make a difference.
Documentation
¶
Overview ¶
Package main is the entry point for the application. It reads the server configuration info, initializes the server.Factory, wires up routes to the appropriate handlers, then starts the HTTP/HTTPS server.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package build contains build objects, which are passed to HTML templates to generate HTML pages.
|
Package build contains build objects, which are passed to HTML templates to generate HTML pages. |
|
Package config includes definitions for the Emissary configuration file, along with adapters for reading/writing from the filesystem or a mongodb database.
|
Package config includes definitions for the Emissary configuration file, along with adapters for reading/writing from the filesystem or a mongodb database. |
|
Package domain contains the domain-level Factory, along with the realtime client/server for SSE connections.
|
Package domain contains the domain-level Factory, along with the realtime client/server for SSE connections. |
|
Package handler contains all of the HTTP handlers for Emissary.
|
Package handler contains all of the HTTP handlers for Emissary. |
|
Package middleware contains HTTP middleware that is specific to Emissary.
|
Package middleware contains HTTP middleware that is specific to Emissary. |
|
Package model contains all of the domain model objects that are used in the system.
|
Package model contains all of the domain model objects that are used in the system. |
|
step
Package Step encapsulates the DATA required for each pipeline step in the builder.
|
Package Step encapsulates the DATA required for each pipeline step in the builder. |
|
Package queries contains all of the custom queries required by this application that DO NOT run through the standard `data` package.
|
Package queries contains all of the custom queries required by this application that DO NOT run through the standard `data` package. |
|
Package server contains the server.Factory, which is the root level factory for the system.
|
Package server contains the server.Factory, which is the root level factory for the system. |
|
Package service includes all of the services used in Emissary.
|
Package service includes all of the services used in Emissary. |
|
Package tools contains..
|
Package tools contains.. |
|
cacheheader
Package cacheheader provides a simple parser and serializer for http `Cache-Control` headers
|
Package cacheheader provides a simple parser and serializer for http `Cache-Control` headers |
|
camper
Camper is an implementation of FEP-3b86 Activity Intents.
|
Camper is an implementation of FEP-3b86 Activity Intents. |
|
channels
Package channels includes some nifty tools for manipulating channels
|
Package channels includes some nifty tools for manipulating channels |
|
convert
Package convert contains Emissary-specific conversions to and from various export formats.
|
Package convert contains Emissary-specific conversions to and from various export formats. |
|
dataset
Package dataset contains some sets of static data that are embedded into Emissary.
|
Package dataset contains some sets of static data that are embedded into Emissary. |
|
hmac
Package hmac contains some nifty tools for manipulating HMAC signatures.
|
Package hmac contains some nifty tools for manipulating HMAC signatures. |
|
id
Package id provides some nifty tools for manipulating mongodb objectIDs.
|
Package id provides some nifty tools for manipulating mongodb objectIDs. |
|
random
Package random contains some nifty tools for generating rantom numbers.
|
Package random contains some nifty tools for generating rantom numbers. |
|
s3uri
Package s3uri parses and generates URI strings for Amazon S3 resources.
|
Package s3uri parses and generates URI strings for Amazon S3 resources. |
|
set
Package set contains some nifty tools for manipulating sets of data, including implementations for slices AND maps.
|
Package set contains some nifty tools for manipulating sets of data, including implementations for slices AND maps. |
|
tinyDate
Package tinyDate provides a nifty way to format dates, just like those fancy tech-bro's do in Silicon Valley.
|
Package tinyDate provides a nifty way to format dates, just like those fancy tech-bro's do in Silicon Valley. |
|
val
Package val is a light and cheap collection of validators.
|
Package val is a light and cheap collection of validators. |