magik-server

a simple HTTP server with some nice magik.

Getting Started

Install the package (globally) and start the server:

$ npm install -g magik-server
$ magik-server

About

magik-server is a small webserver that is intended for use during the development of front-end web applications and websites. There are quite a few configuration options that can be set using command line switches, see below. Also there's the possibility to influence server responses using query string parameters.

Index

• Getting started
• About
• Documentation
  • Command line switches
    • -a
    • --cors
    • -D
    • -e
    • -h
    • -H
    • -i
    • -n
    • -o
    • -p
    • -r
    • -s
    • -t
    • -u
    • -v
  • Query String Parameters
• Examples
• Contributin
• License

Documentation

To display all command line options use the -h or --help switch

$ magik-server --help

Command line options

In this section all the available command line options are listed.

IP Address

-a --address Set the IP address the server is bound to. Default: localhost

$ magik-server -a 10.1.1.10

CORS Headers

--cors Enable sending of CORS headers.

$ magik-server --cors

no directory listing

-D --no-dirs Disable directory listing. By default, when no suitable file is found to serve, a directory listing will be displayed.

$ magik-server -D

extension for the default index

-e --extensions Adds one or more extensions to use to look up the default index page. By default magikServer looks for: html, htm, js.

# add one extension 
$ magik-server -e coffee
 
# add more than one extension 
$ magik-server -e coffee, jade, styl

Help

-h --help Displays a list of all available command line options

show hidden files

-H --hidden Enables the display of hidden files. By default, files starting with a dot are hidden in directory listings, use this switch to show them.

index file(s)

-i --index Adds one or more files that will be used as an index page. By default magikServer looks for files with these names in the document root, index, default, main, app. More files can be added as a comma delimeted list:

$ magik-server -i my-index, my-app, my-other-index

custom 404 page

-n --not-found Adds the path to a custom 404 page. This path is relative to the document root.

$ magik-server -n error-pages/404.html

open browser

-o --open Automagically open the standard system web browser, after the server has started.

port number

-p --port Sets the port number you wish to use for this server instance. If the port number is already in use, the next available port will be automagically selectd. The default port is 8080

$ magik-server -p 8090

document root

-r --root Sets the document root. Files from this folder will be served as if they are on / in the browser.

$ magik-server -r app

HTTP response status code

-s --statusCode Sets the HTTP response code globally. Every response will have this status code. You may also force response codes by using a query string parameter. The default query string parameter is magik-status, but you can also change this to any URL save string.

$ magik-server -s 201
$ magik-server -s my-status-param

response time

-t --time Sets the response time globally in milliseconds. Every reponse will take (at least) this amount of time. You may also force response times by using a query string parameter. The default query string parameter is magik-time, but you can also change this to any URL save string.

$ magik-server -t 3000
$ magik-server -t my-time-param

character encoding

-u --encoding Sets the default character encoding of the files served. This defaults to UTF-8 and usually doesn't have to be changed.

$ magik-server -u cp-1252

version information

-v --version Displays version information of magik-server

$ magik-server -v

Query String Parameters

magikServer allows you to use query string parameters to change certain behaviours. At this moment you can use these:

magik-status Sets the HTTP response status code for this request. That means, the response is certain to have the supplied status code. You can also change the name of the parameter during startup, using the -s switch. See also -s

magik-time Sets the response time for this request. That means that the response will wait at least the supplied amount of milliseconds before it is send. You can also change the name of the parameter during startup, using the -t switch. See also -t.

Examples

Below you'll find a couple of commonly used ways to start up magik-server.

Start the server on localhost on port 8080

$ magik-server

Show help info:

$ magik-server -h

Start the server on port 8090, set the document root to the app folder and set index to my-app.html

$ magik-server -p 8090 -r app -i my-app.html

Set the response time query string parameter to a custom value, so you can make requests that will honour the set time value (in ms), like this one: http://localhost:8080/slow-server-response.html?wait=3000

$ magik-server -t wait

You can also set a global response time that will used for all responses

magik-server -t 3000

Set a custom HTTP response code query string parameter so it can be used in requests like this one: http://localhost:8080/rest-service.json?status=201

$ magik-server -s status

You can also set a global response status code that will always be returned

$ magik-server -s 202

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

License

Copyright (c) 2014 Bjørn Wikkeling [e-mail] bjorn.wikkeling.com

Licensed under the MIT license.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

                          _  _     _____
                         (_)| |   /  ___|
 _ __ ___    __ _   __ _  _ | | __\ `--.   ___  _ __ __   __  ___  _ __
| '_ ` _ \  / _` | / _` || || |/ / `--. \ / _ \| '__|\ \ / / / _ \| '__|
| | | | | || (_| || (_| || ||   < /\__/ /|  __/| |    \ V / |  __/| |
|_| |_| |_| \__,_| \__, ||_||_|\_\\____/  \___||_|     \_/   \___||_|
                    __/ |
                   |___/

---