ws

README

ws

A nimble web server

ws is a prototyping platform for web based services and websites.

ws has a minimal feature set

• A simple static file webserver
  • quick startup
  • activity logged to the console
  • supports http2 out of the box
• A simple server side JavaScript runner for proxing remote JSON resources
  • if you need more, check out NodeJS
• A project setup option called init

Configuration

You can configure ws with command line options or environment variables. Try ws -help for a list of command line options.

Environment variables

• WS_URL the URL to listen for by ws
  • default is http://localhost:8000
• WS_HTDOCS the directory of your static content you need to serve
  • the default is ./htdocs
• WS_JSDOCS the directory for any server side JavaScript processing
  • the default is ./jsdocs (if not found then server side JavaScript is turned off)
• WS_SSL_KEY the path the the SSL key file (e.g. etc/ssl/site.key)
  • default is empty, only checked if your WS_URL is starts with https://
• WS_SSL_CERT the path the the SSL cert file (e.g. etc/ssl/site.crt)
  • default is empty, only checked if your WS_URL is starts with https://

Command line options

• -url overrides WS_URL
• -htdocs overrides WS_HTDOCS
• -jsdocs overrides WS_JSDOCS
• -ssl-key overrides WS_SSL_KEY
• -ssl-pem overrides WS_SSL_PEM
• -init triggers the initialization process and creates a setup.bash file
• -h, -help displays the help documentation
• -v, -version display the version of the command
• -l, -license displays license information

Running ws without environment variables or command line options is an easy way to server your current working directory's content out as http://localhost:8000.

The Server Side JavaScript implementation

The server side JavaScript support in ws is intended to make it easy to pull in JSON resources from the web for integration and testing with your static website content. It uses a JavaScript engine called otto.

otto is a JavaScript virtual machine written by Robert Krimen. Each JavaScript file in the jsdocs directory tree becomes a URL end point or route. E.g. jsdocs/example-1.js becomes the route /example-1. example-1. Each of the server side JavaScript files should contain a closure accepting a "Request" and "Response" object as parameters. E.g.

    /* example-1.js - a simple example of Request and Response objects */
    (function (req, res) {
        var header = req.Header;

        res.setHeader("content-type", "text/html");
        res.setContent(
          "<p>Here is the Header array received by this request</p>" +
          "<pre>" + JSON.stringify(header) + "</pre>");
    }(Request, Response));

Assuming server side JavaScript is enabled then this end point would rendered with a content type of "text/html". The body should be holding the paragraph and pre element.

Some additional functions are provided to facilitate server side JavaScript development--

• http related
  • WS.httpGet(url, array_of_headers) which performs a HTTP GET
  • WS.httpPost(url, array_of_headers, payload) which performs an HTTP POST
• os related
  • WS.getEnv(varname) which will read an environment variable

The server side JavaScripts cannot call other JavaScript files or modules. This was a deliberate design decission as NodeJS is a widely available server side JS environment with a large community and amply documented at this point in time.

Need to quickly build out a website from Markdown files or other JSON resources? Take a look at mkpage.

Installation

ws is available as precompile binaries for Linux, Mac OS X, and Windows 10 on Intel. Additional binaries are provided for Raspbian on ARM6 adn ARM7. Follow the INSTALL.md instructions to download and install the pre-compiled binaries.

If you have Golang installed then ws can be installed with the go get command.

    go get github.com/caltechlibrary/ws/...

Compiling from source

Required

• Golang version 1.7 or better
• A 3rd Party Go package
  • Otto by Robert Krimen, MIT license
    • a JavaScript interpreter written in Go
    • "go gettable" with go get github.com/robertkrimen/otto/...

Here's my basic approach to get things setup. Go 1.7 needs to be already installed.

  git clone https://github.com/caltechlibrary/ws
  cd ws
  go get -u github.com/robertkrimen/otto
  go test
  go build
  go build cmds/ws/ws.go

If everything compiles fine then I do something like this--

  go install cmds/ws/ws.go

LICENSE

copyright (c) 2016 Caltech See LICENSE for details

Documentation

Overview

Package ws provides the core library used by cmds/ws/ws.go

@author R. S. Doiel, <rsdoiel@caltech.edu>

Copyright (c) 2016, Caltech All rights not granted herein are expressly reserved by Caltech

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Index

• Constants
• func JSPathToRoute(p string, cfg *Configuration) (string, error)
• func NewJSEngine(w http.ResponseWriter, r *http.Request) *otto.Otto
• func ReadJSFiles(jsDocs string) (map[string][]byte, error)
• func ToStruct(value otto.Value, aStruct interface{}) error
• type Configuration
  • func (config *Configuration) GenerateKeyAndCert() error
  • func (config *Configuration) Getenv() error
  • func (config *Configuration) InitializeProject() (string, error)
  • func (config *Configuration) String() string
  • func (config *Configuration) Validate() error
• type JSRequest
• type JSResponse

Constants

const (
	// Version is used as a release number for ws
	Version = "0.0.8"
)

Functions

func JSPathToRoute

func JSPathToRoute(p string, cfg *Configuration) (string, error)

JSPathToRoute converts a JSDocs path to a JavaScript file into a web server route.

func NewJSEngine

func NewJSEngine(w http.ResponseWriter, r *http.Request) *otto.Otto

NewJSEngine creates a new JavaScript version machine from otto.New() but adds additional functionality such as WS.Getenv(), WW.httpGet(), WS.httpPost()

func ReadJSFiles

func ReadJSFiles(jsDocs string) (map[string][]byte, error)

ReadJSFiles walks a directory tree and then return the results as a map of paths and JS source code in []byte.

func ToStruct

func ToStruct(value otto.Value, aStruct interface{}) error

ToStruct will attempt populate a struct passed in as a parameter.

ToStruct returns an error if it runs into a problem.

Example: a := struct{One int, Two string}{} val, _ := vm.Run(`(function (){ return {One: 1, Two: "two"}}())`) _ := ToSruct(val, &a) fmt.Printf("One: %d, Two: %s\n", a.One, a.Two)

Types

type Configuration

type Configuration struct {
	URL     *url.URL
	HTDocs  string
	JSDocs  string
	SSLKey  string
	SSLCert string
}

Configuration provides the basic settings used by _ws_ and _wsint_ commands.

func (*Configuration) GenerateKeyAndCert

func (config *Configuration) GenerateKeyAndCert() error

GenerateKeyAndCert will generate a new SSL Key/Cert pair if none exist. It will return a error if they already exist.

func (*Configuration) Getenv

func (config *Configuration) Getenv() error

Getenv scans the environment variables and updates the fields in the configuration. If there is a problem parsing WS_URL then an error is returned.

func (*Configuration) InitializeProject

func (config *Configuration) InitializeProject() (string, error)

InitializeProject scans the current working path and identifies what directories need to be created, creates them, adds SSL keys/certs if needed and returns a suggested configuration file.

func (*Configuration) String

func (config *Configuration) String() string

String returns a multiline block of text suitable to save in a text file.

func (*Configuration) Validate

func (config *Configuration) Validate() error

Validate performs a sanity check of the values in the configuration Returns nil if OK otherwise returns error

type JSRequest

type JSRequest struct {
	URL    *url.URL               `json:"url"`
	Method string                 `json:"method"`
	Body   []byte                 `json:"body"`
	Form   map[string]interface{} `json:"form"`
}

JSRequest provides a struct for server side JS request processing

type JSResponse

type JSResponse struct {
	Code    int64               `json:"code,omitempty"`
	Headers []map[string]string `json:"headers,omitempty"`
	Content string              `json:"content,omitempty"`
}

JSResponse provides a structure for server side JS responses