Rustful
A light HTTP framework for Rust, with REST-like features. The main purpose of Rustful is to create a simple, modular and non-intrusive foundation for HTTP applications. It has a mainly stateless structure, which naturally allows it to run both as one single server and as multiple instances in a cluster.
Some of the features are:
- Generic response handlers. Just use a function or implement the Handler trait.
- Unified log system to make sure everything is working together.
- Some handy macros reduces the risk for typos and makes life easier.
- Pluggable request and response filtering.
- Variables and recursive wildcards in routes.
#Getting Started
##Cargo.toml Entries
Add the following lines to your Cargo.toml
file:
[]
= "0.4"
###Cargo Features
Some parts of Rustful can be toggled using Cargo features:
rustc_json_body
- Parse the request body as JSON. Enabled by default.ssl
- Enable SSL, and thereby HTTPS. Enabled by default.multipart
- Enable parsing ofmultipart/form-data
requests. Enabled by default.
###Using SSL
Note that the ssl
feature requires OpenSSL to be installed in one way or
another. See https://github.com/sfackler/rust-openssl#building for more
instructions.
##Write Your Server
Here is a simple example of what a simple project could look like. Visit
http://localhost:8080
or http://localhost:8080/Olivia
(if your name is
Olivia) to try it.
//Include macros to be able to use `insert_routes!`.
extern crate rustful;
use Error;
use ;
//Dodge an ICE, related to functions as handlers.
);
##Contributing
Contributions are always welcome, even if it's a small typo fix (or maybe I should say "especially typo fixes"). You can fork the project and open a pull request with your changes, or create an issue if you just want to report or request something. Are you not sure about how to implement your change? Is it still a work in progress? Don't worry. You can still open a pull request where we can discuss it and do it step by step.
New features are as welcome as fixes, so pull requests and proposals with enhancements are very much appreciated, but please explain your feature and give a good motivation to why it should be included. It makes things much easier, both for reviewing the feature and for those who are not as familiar with how things work. You can always open an issue where we can discuss the feature and see if it should be included. Asking is better than assuming!
###Testing
Rustful is tested on Linux, using Travis, and on Windows, using AppVeyor and a pull request will not be approved unless it passes these tests. It is therefore a good idea to run tests locally, before pushing your changes, so here is a small list of useful commands:
cargo test
- Basic unit, documentation and compile tests.cargo build --no-default-features
- Check if the most minimal version of Rustful builds.cargo build --no-default-features --features "feature1 feature2"
- Check if Rustful with onlyfeature1
andfeature2
enabled builds.cargo run --example example_name
- check if the exampleexample_name
behaves as expected (see theexample
directory).
Travis and AppVeyor will run the tests with the strict
feature enabled. This
turns warnings and missing documentation into compile errors, which may be
harsh, but it's for the sake of the user. Everything should have a description
and it's not nice to see warnings from your dependencies when you are
compiling your project, right? It's therefore recommend that you run your own
tests with the strict
feature enabled before pushing, just to see if you
missed something.
User facing Cargo features are tested one at the time, using
scripts/test_features.sh
, so any newly new user facing feature should be
added to its feature list (as well as the list in this README). Development
features, such as strict
, or features that only exists as dependencies for
other features does not count as user facing.