prax.cr v0.8.1

Rack proxy server for development (Crystal port)

Prax

Rack proxy server for development

This is an (almost) complete rewrite of Prax in Crystal, a Ruby-inspired language that compiles down to LLVM. This version should avoid problems with version managers, since Prax is now a binary application that don't rely on Ruby anymore (except for Rack and rackup).

Please refer to the wiki for more information:

Install

You can download a Debian / Ubuntu package for 64bits kernel on the releases page. For other systems, you'll have to follow the Manual Install Guide.

How it works

  1. resolves *.test and *.localhost domains to 127.0.0.1 and ::1 (localhost);
  2. redirects the :80 and :443 ports to :20559 and :20558;
  3. receives incoming HTTP requests and extracts the hostname (eg: myapp.test);
  4. serves static files directly if they exist;
  5. otherwise spawns a Rack applications (found at ~/.prax/myapp) if any;
  6. and proxies the request to the Rack aplication or a specified port for port forwarding.

Domain Resolver

systemd

If your distribution uses systemd-resolved, just use the .localhost TLD instead of .test —be prepared to fight against systemd if you want to use another TLD, or consider switching to a systemd free Linux.

.test TLD

Prax proposes 2 solutions to resolve .test and .localhost domains:

  • a dnsmasq configuration, either throught NetworkManager or by installing dnsmasq manually (eg. through your Linux distribution package);
  • an obsolete and deprecated NSSwitch extension, only compatible wih glibc and no longer compatible with Google Chrome/Chromium, and certainly more.

xip.io

Prax supports http://xip.io/ domains, so you can use myapp.129.168.0.1.xip.io for example. This is useful when using an external device like a smartphone, tablet or another computer to test your websites on.

Custom TLD

If .test or .localhost domains are not your cup of tea, no problem! Prax will route requests from any TLD to the applications in your ~/.prax directory, as long as the domain resolves to localhost.

For instance, if you wished to visit myapp.dev instead of myapp.test, you could create dnsmasq configuration to resolve .dev domains to localhost, too:

$ sudo tee /etc/dnsmasq.d/dev <<EOF
local=/dev/
address=/dev/127.0.0.1
address=/dev/::1
EOF
$ sudo service dnsmasq restart

Port Redirections

The port redirections are iptables rules, that are installed and removed using an initd script. The script redirects the port :80 and :443 on 127.0.0.1 and for each wlanX and ethX devices found on your machine, to allow incoming traffic, so you can use http://xip.io to test on external devices, as mentioned above.

You can install or remove the redirections with:

$ prax iptables [start|stop|restart|status]

Distribution packages should configure an init service to always install the iptables rules on machine startup or before starting prax (warning: this requires root privileges).

License

Prax is distributed under the CeCILL 2.1 license. Please see LICENSE for details.

HTML templates for rendering errors are from Pow!!, by Sam Stephenson and Basecamp, and are under the MIT license.

The NSSwitch extension originaly come from Hoof, by pyromaniac, and is under the MIT license.

Credits

Prax wouldn't exist without Pow!! by Sam Stephenson and Basecamp. Prax is nothing more but a reimplementation (in another language) with Linux compatibility in mind.

CHANGELOG

v0.8.1 - 2018-12-08

Fixes:

  • Prax hung forever when reaping child processes.
  • Crystal 0.27 compatibility.

v0.8.0 - 2018-09-07

Enhancements:

  • Allow to port forward to specific host with host:port host file (and [ipv6]:port for IPv6 addresses.

Breaking changes:

  • default to .test TLD by default instead of Google-owned .dev domain that requires HTTPS to be configured.

Fixes:

  • HTTP headers lookups are case-insensitive.
  • Crystal 0.24+ compatibility.
  • Debian 9 packaging issues.

v0.7.0

Enhancements:

  • Added --ssl-port configuration option.
  • Added --timeout (PRAX_TIMEOUT) configuration option to wait longer or shorter than 60 seconds for applications to start.
  • Detect real hardware devices to apply port redirection on (supports weird systemd predictable interface names).
  • Compatibility with the dotenv gem.

Breaking changes:

  • Setting environment variables via .env files has been removed. Use the .praxrc shell file in your project to set environment variables instead.

v0.6.1

Fixes:

  • Only redirect traffic from wlan/eth devices.

v0.6.0

Enhancements:

  • Source .praxrc shell files in projects (eg: to configure variables, version managers, ...)
  • Move iptables rules to prax iptables command
  • Upgraded to Crystal 0.18+

Fixes:

  • Multiple Forwarding of repeated headers (cookies were broken)
  • Unescape filenames before searching in the public folder

v0.5.1

Fixes:

v0.5.0

Enhancements:

  • Upgraded to Crystal 0.8.0 (uses standard Process.new, dropped deprecations)
  • Generic SIGCHLD handler to reap zombie children (no more reap threads)

Fixes:

  • Proxy middleware was always run after public file middleware

v0.4.2

Features:

  • Prax now logs on ~/.prax/_logs.prax.log when daemonized

Fixes:

  • Prax crashed when starting as a daemon
  • Prax hanged forever with concurrent requests to an app while it spawned

v0.4.1

  • Better Debian packages
  • Compatibility with Crystal v0.7.3

v0.4.0

  • Compatibility with Crystal v0.7.x
  • Handle requests in an event loop, see #3

v0.3.0

  • Start an HTTPS server along the HTTP server, see #5
  • Sets proxy headers (X-Forwarded-For, ...), see #6
  • Handle requests with a pool of threads (avoids a memory leak, see #8)
  • Resolve dev domains using dnsmasq instead of NSSwitch, see #9

v0.2.0

Initial release.

Github statistic:
  • 129
  • 0
  • 16
  • 8
  • 12
  • 9 days ago

License:

Other

Links: