zelo72
/
flodgatt
mirror of https://github.com/mastodon/flodgatt
1
0
Fork 0
Code Issues Releases Wiki Activity

Change name of project in README.md (#25)

This commit is contained in:
Eugen Rochko 2019-07-10 23:37:41 +02:00 committed by Daniel Sockwell
parent 4097783b56
commit f1f0c8e705
1 changed files with 28 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
README.md
View File

@ -1,64 +1,40 @@
# Mastodon Streaming Server
A WIP blazingly fast drop-in replacement for the Mastodon streaming api server.
Flóðgátt
========
## Current status
The streaming server is currently a work in progress. However, it is now testable and, if
configured properly, would theoretically be usable in production—though production use is
not advisable until we have completed further testing. I would greatly appreciate any testing,
bug reports, or other feedback you could provide.
[![Build Status](https://travis-ci.com/tootsuite/flodgatt.svg?branch=master)](https://travis-ci.com/tootsuite/flodgatt)
## Installation
Installing the WIP version requires the Rust toolchain (the released version will be available
as a pre-compiled binary). To install, clone this repository and run `cargo build` (to build
the server) `cargo run` (to both build and run the server), or `cargo build --release` (to
build the server with release optimizations).
A blazingly fast drop-in replacement for the Mastodon streaming API server.
## Connection to Mastodon
The streaming server expects to connect to a running development version of Mastodon built off of
the `master` branch. Specifically, it needs to connect to both the Postgres database (to
authenticate users) and to the Redis database. You should run Mastodon in whatever way you
normally do and configure the streaming server to connect to the appropriate databases.
> **Current status:** This server is currently a **work in progress**. However, it is now testable and, if configured properly, would theoretically be usable in production—though production use is not advisable until we have completed further testing. I would greatly appreciate any testing, bug reports, or other feedback you could provide.
## Configuring
You may edit the configuration variables in the `config.rs` module. You can also overwrite the
default config variables in the `.env` file. Note that, by default, this server is configured
to run on port 4000. This allows for easy testing with the development version of Mastodon
(which, by default, is configured to communicate with a streaming server running on
`localhost:4000`). However, it also conflicts with the current/Node.js version of Mastodon's
streaming server, which runs on the same port. Thus, to test this server, you should disable
the Node streaming server or move it to a non-conflicting port.
## Installation
Installing from source requires the Rust toolchain. Clone this repository and run `cargo build` (to build the server), or `cargo build --release` (to build the server with release optimizations).
### Configuring
The streaming server uses the same environment variables as the rest of Mastodon, which can either be passed to the process the standard way or through a `.env` file.
### Running
You can run the server with `cargo run`. Alternatively, if you built the sever using `cargo build` or `cargo build --release`, you can run the executable produced in the `target/build/debug` folder or the `target/build/release` folder.
## Documentation
Build documentation with `cargo doc --open`, which will build the Markdown docs and open them
in your browser. Please consult those docs for a detailed description of the code
structure/organization. The documentation also contains additional notes about data flow and
options for configuration.
## Running
As noted above, you can run the server with `cargo run`. Alternatively, if you built the sever
using `cargo build` or `cargo build --release`, you can run the executable produced in the
`target/build/debug` folder or the `target/build/release` folder.
Build documentation with `cargo doc --open`, which will build the Markdown docs and open them in your browser. Please consult those docs for a detailed description of the code structure/organization. The documentation also contains additional notes about data flow and options for configuration.
## Unit and (limited) integration tests
You can run basic unit test of the public Server Sent Event endpoints with `cargo test`. You can
run integration tests of the authenticated SSE endpoints (which require a Postgres connection)
with `cargo test -- --ignored`.
## Manual testing
Once the streaming server is running, you can also test it manually. You can test it using a
browser connected to the relevant Mastodon development server. Or you can test the SSE endpoints
with `curl`, PostMan, or any other HTTP client. Similarly, you can test the WebSocket endpoints
with `websocat` or any other WebSocket client.
You can run basic unit test of the public Server Sent Event endpoints with `cargo test`. You can run integration tests of the authenticated SSE endpoints (which require a PostgreSQL connection) with `cargo test -- --ignored`.
## Memory/CPU usage
Note that memory usage is higher when running the development version of the streaming server (the
one generated with `cargo run` or `cargo build`). If you are interested in measuring RAM or CPU
usage, you should likely run `cargo build --release` and test the release version of the executable.
### Manual testing
## Load testing
I have not yet found a good way to test the streaming server under load. I have experimented with
using `artillery` or other load-testing utilities. However, every utility I am familiar with or
have found is built around either HTTP requests or WebSocket connections in which the client sends
messages. I have not found a good solution to test receiving SSEs or WebSocket connections where
the client does not transmit data after establishing the connection. If you are aware of a good
way to do load testing, please let me know.
Once the streaming server is running, you can also test it manually. You can test it using a browser connected to the relevant Mastodon development server. Or you can test the SSE endpoints with `curl`, PostMan, or any other HTTP client. Similarly, you can test the WebSocket endpoints with `websocat` or any other WebSocket client.
### Memory/CPU usage
Note that memory usage is higher when running the development version of the streaming server (the one generated with `cargo run` or `cargo build`). If you are interested in measuring RAM or CPU usage, you should likely run `cargo build --release` and test the release version of the executable.
### Load testing
I have not yet found a good way to test the streaming server under load. I have experimented with using `artillery` or other load-testing utilities. However, every utility I am familiar with or have found is built around either HTTP requests or WebSocket connections in which the client sends messages. I have not found a good solution to test receiving SSEs or WebSocket connections where the client does not transmit data after establishing the connection. If you are aware of a good way to do load testing, please let me know.