Skip to content
This repository
Browse code

updated README notice

  • Loading branch information...
commit 01ae80f4043c7647e9eadda4c6b2eb0370ae9bbf 1 parent e176df7
Roberto Ostinelli authored

Showing 1 changed file with 181 additions and 0 deletions. Show diff stats Hide diff stats

  1. +181 0 README.md
181 README.md
Source Rendered
@@ -19,7 +19,188 @@ Especially since the recent heavy development of Cowboy's HTTP server, I believe
19 19 Thank you to everyone that has been supporting Misultin in these years. Hopefully its **code usability**, which I still believe to be unmatched (well, I have developed it so how could I feel differently about this ^^_), will provide inspiration for some library interfaces.
20 20
21 21 Best to you all,
  22 +***
  23 +***
  24 +***
  25 +***
  26 +
  27 +Misultin development has been discontinued.
  28 +
  29 +There currently are three main webserver _libraries_ which basically do similar things:
  30 +
  31 + * [Mochiweb](https://github.com/mochi/mochiweb)
  32 + * [Cowboy](https://github.com/extend/cowboy)
  33 + * [Misultin](https://github.com/ostinelli/misultin)
  34 +
  35 +**Mochiweb** has been around the block for a while and it's proven solid in production, I can only recommend it for all basic webserver needs you might have.
  36 +**Cowboy** has a very interesting approach since it allows to use multiple TCP and UDP protocols on top of a common acceptor pool. It is a very modern approach, is very actively maintained and many projects are starting to be built around it.
  37 +
  38 +Especially since the recent heavy development of Cowboy's HTTP server, I believe there is way too much duplication of efforts going on here. This is why Misultin's current 'state of the art' has been frozen in the latest tag, [v0.9](https://github.com/ostinelli/misultin/tree/misultin-0.9), to support all the companies currently using Misultin in their production environment. I'm here to provide help, if needed, in moving away from it. Thus, this server should be robust and stable enough to continue serving your needs for some time.
  39 +
  40 +Instead of letting this library stand here without this notice, and getting developers still use this project, I have preferred to explicitly state to gradually move away from it, so that efforts can be concentrated around one server library only. It's hard enough to let one 'child' like this one go, but I believe it's best for the whole Erlang community.
  41 +
  42 +Thank you to everyone that has been supporting Misultin in these years. Hopefully its **code usability**, which I still believe to be unmatched (well, I have developed it so how could I feel differently about this ^^_), will provide inspiration for some library interfaces.
  43 +
  44 +Best to you all,
  45 +
  46 +r.
  47 +
  48 +***
  49 +***
  50 +***
  51 +***
  52 +
  53 +# MISULTIN
  54 +
  55 +Misultin is an HTTP(S) library which can easily be embedded in your own application.
  56 +
  57 +https://github.com/ostinelli/misultin
  58 +
  59 +`>-|-|-(°>`
  60 +
  61 +
  62 +# Features
  63 +
  64 + * _Very_ fast
  65 + * HTTP and HTTPS
  66 + * Supports multiple **Websocket** protocols (draft-hixie-68, draft-hixie-76, draft-hybi-10 and draft-hybi-17)
  67 + * **Cookies**
  68 + * **Session** Variables
  69 + * Allows for Chunked and Byte **streaming responses**
  70 + * Allows for **streaming file upload** (via Chunked Encoding)
  71 + * Can serves static files from a ```static``` directory (though in production you should consider a specific server such as [nginx](http://nginx.org/) to do so)
  72 + * Has Many customization options (maximum allowed connections, maximum body size, ...)
  73 + * Has a callback function for your **logging** needs
  74 + * Supports **Unicode**
  75 + * Can start multiple servers on a single node
  76 + * Can be used with or without Parametrized Modules
  77 + * Can traps the client closing a browser in Comet applications
  78 + * It's very easy to use
  79 +
  80 +
  81 +# Quick Start
  82 +
  83 + The typical 'Hello World" example code is:
  84 +
  85 +```erlang
  86 +
  87 +-module(misultin_hello_world).
  88 +-export([start/0, stop/0]).
  89 +
  90 +% start misultin http server
  91 +start() ->
  92 + misultin:start_link([{port, 8080}, {loop, fun(Req) -> handle_http(Req) end}]).
  93 +
  94 +% stop misultin
  95 +stop() ->
  96 + misultin:stop().
  97 +
  98 +% callback on request received
  99 +handle_http(Req) ->
  100 + Req:ok("Hello World.").
  101 +```
  102 +
  103 +Issuing the ```start/0``` command will start an HTTP server on port 8080, which will respond to every request with an "Hello World" text.
  104 +
  105 +# Examples
  106 +
  107 +Misultin comes [packed with examples](https://github.com/ostinelli/misultin/tree/master/examples/).
  108 +
  109 +#### Simple Examples
  110 +
  111 + * [Hello World](https://github.com/ostinelli/misultin/tree/master/examples/misultin_hello_world.erl)
  112 + * [Querystring Variables](https://github.com/ostinelli/misultin/tree/master/examples/misultin_get_variable.erl)
  113 + * [Querystring and POST Variables](https://github.com/ostinelli/misultin/tree/master/examples/misultin_echo.erl)
  114 + * [REST](https://github.com/ostinelli/misultin/tree/master/examples/misultin_rest.erl)
  115 + * [Set and Get Cookies](https://github.com/ostinelli/misultin/tree/master/examples/misultin_cookies_example.erl)
  116 + * [Set and Get Session Variables](https://github.com/ostinelli/misultin/tree/master/examples/misultin_sessions_example.erl)
  117 + * [Serve a Static file for download](https://github.com/ostinelli/misultin/tree/master/examples/misultin_file.erl)
  118 + * [Serving files from a Static directory](https://github.com/ostinelli/misultin/tree/master/examples/misultin_static.erl)
  119 + * [File Upload](https://github.com/ostinelli/misultin/tree/master/examples/misultin_file_upload.erl)
  120 + * [HTTPS example](https://github.com/ostinelli/misultin/tree/master/examples/misultin_ssl.erl)
  121 + * [Performing a simple redirection](https://github.com/ostinelli/misultin/tree/master/examples/misultin_redirect.erl)
  122 + * [Serving compressed content](https://github.com/ostinelli/misultin/tree/master/examples/misultin_compress.erl)
  123 + * [Logging Access](https://github.com/ostinelli/misultin/tree/master/examples/misultin_access_log.erl)
  124 +
  125 +#### Websockets
  126 +
  127 + * [Simple Websocket](https://github.com/ostinelli/misultin/tree/master/examples/misultin_websocket_example.erl)
  128 + * [Simple Websocket on SSL](https://github.com/ostinelli/misultin/tree/master/examples/misultin_websocket_example_ssl.erl)
  129 + * [Websocket exposing the close event](https://github.com/ostinelli/misultin/tree/master/examples/misultin_websocket_event_example.erl)
  130 + * [Websocket exposing the close event, example 2](https://github.com/ostinelli/misultin/tree/master/examples/misultin_websocket_event_example2.erl)
  131 + * [Access Session Variables from Websockets](https://github.com/ostinelli/misultin/tree/master/examples/misultin_websocket_sessions_example.erl)
  132 +
  133 +
  134 +#### Comets
  135 +
  136 + * [Long Polling](https://github.com/ostinelli/misultin/tree/master/examples/misultin_comet_long_polling.erl)
  137 + * [iFrame Technique](https://github.com/ostinelli/misultin/tree/master/examples/misultin_comet_iframe.erl)
  138 + * [iFrame Technique using the close event](https://github.com/ostinelli/misultin/tree/master/examples/misultin_comet_iframe_event.erl)
  139 +
  140 +
  141 +#### More Advanced
  142 +
  143 + * [Sending Chunked Content](https://github.com/ostinelli/misultin/tree/master/examples/misultin_chunked.erl)
  144 + * [Sending Byte Streaming Content](https://github.com/ostinelli/misultin/tree/master/examples/misultin_stream.erl)
  145 + * [Receiving endless streaming Upload](https://github.com/ostinelli/misultin/tree/master/examples/misultin_body_recv.erl)
  146 + * [Unicode](https://github.com/ostinelli/misultin/tree/master/examples/misultin_unicode.erl)
  147 + * [REST with UTF-8](https://github.com/ostinelli/misultin/tree/master/examples/misultin_rest_utf8.erl)
  148 + * [Starting a nameless server](https://github.com/ostinelli/misultin/tree/master/examples/misultin_hello_world_nameless.erl)
  149 + * [Starting multiple servers on a same node, with a custom name](https://github.com/ostinelli/misultin/tree/master/examples/misultin_multiple_servers_custom_name.erl)
  150 + * [Using the HAProxy protocol](https://github.com/ostinelli/misultin/tree/master/examples/misultin_proxy_protocol.erl)
  151 +
  152 +# Module Exports
  153 +
  154 +The complete list of module exports can be found [here](https://github.com/ostinelli/misultin/tree/master/EXPORTS.md).
  155 +
  156 +# Parametrized modules
  157 +
  158 +Some developers hate them, some love them. Misultin allows you to choose if you want to use them or not. The same **Hello World** example shown here above, but without parametrized modules, looks like this:
  159 +
  160 +```erlang
  161 +
  162 +-module(misultin_hello_world).
  163 +-export([start/0, stop/0]).
  164 +
  165 +% start misultin http server
  166 +start() ->
  167 + misultin:start_link([{port, 8080}, {loop, fun(Req) -> handle_http(Req) end}]).
  168 +
  169 +% stop misultin
  170 +stop() ->
  171 + misultin:stop().
  172 +
  173 +% callback on request received
  174 +handle_http(Req) ->
  175 + misultin_req:ok("Hello World.", Req).
  176 +```
  177 +
  178 +# Dependencies
  179 +
  180 +You will need:
  181 +
  182 + * [Erlang](http://www.erlang.org/download.html) >= R14B01
  183 + * [Rebar](https://github.com/basho/rebar) to compile
  184 +
  185 +# Under the hood
  186 +Misultin is built using the OTP principles. When you start it using the ```misultin:start_link/1``` command, you are actually starting a supervisor which handles all of Misultin's servers and modules.
  187 +
  188 +Therefore, in real life applications you should always embed it in your own application. An easy example on how this can be done can be found in the Application Example [here](https://github.com/ostinelli/misultin/tree/master/examples/application).
  189 +
  190 +# SSL Notes
  191 +
  192 +If you are running misultin behind an SSL terminator such as stunnel or stud, and are using websockets, to make the websocket handshakes work, set in the starting options:
  193 +
  194 +```erlang
  195 +{ws_force_ssl, true}
  196 +```
  197 +
  198 +If you are using stunnel to terminate, to make misultin expect a PROXY.. line as per the [proxy protocol](http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt) you can also set in the starting options:
  199 +```erlang
  200 +{proxy_protocol, true}
  201 +```
22 202
  203 +Newer versions of stunnel support this with the "protocol = proxy" config option.
23 204 r.
24 205
25 206 ***

0 comments on commit 01ae80f

Please sign in to comment.
Something went wrong with that request. Please try again.