initial commit

Author: coocood

.gitignore

@@ -0,0 +1,23 @@
+# Compiled Object files, Static and Dynamic libs (Shared Objects)
+*.o
+*.a
+*.so
+
+# Folders
+_obj
+_test
+
+# Architecture specific extensions/prefixes
+*.[568vq]
+[568vq].out
+
+*.cgo1.go
+*.cgo2.c
+_cgo_defun.c
+_cgo_gotypes.go
+_cgo_export.*
+
+_testmain.go
+
+*.exe
+*.test

LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2014 Ewan Chou.
+
+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.

README.md

@@ -0,0 +1,242 @@
+Stadis - Stand-alone Distributed System
+=======================================
+The easiest way to learn, develop and test a distributed system.
+
+Why should I use it?
+====================
+Testing distributed system is very expensive.
+
+It takes a large amount of resources, takes a lot of time to deploy and config.
+
+More importantly, as your application is running on multiple machine,
+it's nearly impossible to coordinate the network state with your application state.
+as a result, there will be lots of error handling code leave untested,
+which can cause serious problem once that actually happen.
+
+With stadis, you can run a multi-data-center distributed system on a single machine.
+
+You can change the topology and node state at any time by a single API call.
+Everything happens exactly the way you want.
+Every network error handling code can be easily covered.
+
+Get started
+===========
+Require Go 1.2+ installed.
+
+Stadis can be used as a library in Go application.
+
+For applications written in other programming language, stadis can be used as a proxy server.
+
+###Use stadis as a library in Go program.
+
+Hello world example
+
+    package main
+
+    import (
+    	"fmt"
+    	"github.com/coocood/stadis"
+    	"io"
+    	"log"
+    	"net/http"
+    	"os"
+    	"time"
+    )
+
+    func main() {
+    	//Start a api server.
+    	go http.ListenAndServe(stadis.Cli.ApiAddr, stadis.NewApiServer())
+    	//Setup the http client dialer.
+    	http.DefaultTransport.(*http.Transport).Dial = stadis.NewDialFunc("matter.metal.gold", 5*time.Second)
+
+    	eagleListener, err := stadis.Listen("tcp", "localhost:8585", "animal.air.eagle")
+    	if err != nil {
+    		log.Fatal(err)
+    	}
+
+    	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request){
+    		w.Write([]byte("hello\n"))
+    	})
+
+    	go http.Serve(eagleListener, nil)
+
+    	time.Sleep(time.Millisecond)
+    	before := time.Now()
+    	resp, err := http.Get("http://localhost:8585/")
+    	if err != nil {
+    		log.Fatal(err)
+    	}
+    	io.Copy(os.Stdout, resp.Body)
+    	resp.Body.Close()
+    	//the latency should be a little more than 888ms which is define at stadis.DefaultConfig.
+    	fmt.Println("latency:", time.Now().Sub(before))
+    }
+
+###Run stadis as a API/proxy server.
+
+Build and Run
+
+    go get github.com/coocood/stadis
+    go build github.com/coocood/stadis/stadiserver
+    ./stadiserver
+
+Now, the stadis API server is started at port `8989`.
+
+Then start a trivial http server as the origin server on port `12345` by run
+
+    go run $GOROOT/src/pkg/net/http/triv.go
+
+Then call the REST API to open a proxy
+
+    curl -X POST 'http://localhost:8989/proxy?clientName=matter.metal.gold&proxyName=animal.air.eagle&proxyPort=8586&originAddr=localhost:12345'
+
+We can ask the API server for the dial state:
+
+    curl 'http://localhost:8989/dialState?clientName=matter.metal.gold&serverPort=8586'
+
+You will get dial state like `{"Latency":444000000,"OK":true}`, the latency unit is nano second.
+Normally you should sleep for that amount of time in your program before actually dial the proxy server.
+If 'OK' is 'false' you should return error or throw an exception.
+
+Then request the proxy server and record the time.
+
+    time curl -i 'http://localhost:8586/counter'
+
+The real time should be a little more than 444ms, which is the roundtrip time from 'matter.metal.gold' to 'animal.air.eagle'.
+
+Configuration
+===============
+Stadis server does not use any config file, it starts with a default configuration, and you can update it by REST API call.
+
+Stadis API server maintains a virtual topology which has three level:'DataCenter', 'Rack' and 'Host'.
+All of them has a 'NodeState' of attributes 'Name', 'Latency', 'InternalDown' and 'ExternalDown' .
+The topology contains multiple 'DataCenter', which contains multiple 'Rack', which in turn contains
+multiple 'Host'.
+
+We all know naming is hard, so I did the hard work for you.
+After spent many hours, I managed to come up with 39 node names.
+The topology has three data centers, each data center has three racks, each rack has three hosts.
+
+    {
+    	"DcDefault":{"Latency":100000000},
+    	"RackDefault":{"Latency":10000000},
+    	"HostDefault":{"Latency":1000000},
+    	"DataCenters":[
+    		{
+    			"Name":"animal",
+    			"Racks":[
+    				{
+    					"Name":"land",
+    					"Hosts":[{"Name":"tiger"},{"Name":"lion"},{"Name":"wolf"}]
+    				},
+    				{
+    					"Name":"sea",
+    					"Hosts":[{"Name":"shark"},{"Name":"whale"},{"Name":"cod"}]
+    				},
+    				{
+    					"Name":"air",
+    					"Hosts":[{"Name":"eagle"},{"Name":"crow"},{"Name":"owl"}]
+    				}
+    			]
+    		},
+    		{
+    			"Name":"plant",
+    			"Racks":[
+    				{
+    					"Name":"fruit",
+    					"Hosts":[{"Name":"apple"},{"Name":"pear"},{"Name":"grape"}]
+    				},
+    				{
+    					"Name":"crop",
+    					"Hosts":[{"Name":"corn"},{"Name":"rice"},{"Name":"wheat"}]
+    				},
+    				{
+    					"Name":"flower",
+    					"Hosts":[{"Name":"rose"},{"Name":"lily"},{"Name":"lotus"}]
+    				}
+    			]
+    		},
+    		{
+    			"Name":"matter",
+    			"Racks":[
+    				{
+    					"Name":"metal",
+    					"Hosts":[{"Name":"gold"},{"Name":"silver"},{"Name":"iron"}]
+    				},
+    				{
+    					"Name":"gem",
+    					"Hosts":[{"Name":"ruby"},{"Name":"ivory"},{"Name":"pearl"}]
+    				},
+    				{
+    					"Name":"liquid",
+    					"Hosts":[{"Name":"water"},{"Name":"oil"},{"Name":"wine"}]
+    				}
+    			]
+    		}
+    	]
+    }
+
+In default configuration, each data center has 100ms latency, each rack has 10ms latency, each host has 1ms latency.
+
+So the latency from 'matter.metal.gold' to 'animal.air.eagle' should be "1ms+10ms+100ms+100ms+10ms+1ms = 222ms"
+
+The round trip time should be 444ms, so the total time to create a connection
+and then make a http request from 'gold' to 'eagle' should be a little more than 888ms.
+
+REST API
+================
+
+- Update configuration with json payload like the default config shown above.
+
+        POST /config
+
+
+- Update node state with json body like `{"Latency":10000000,"InternalDown":false,"ExternalDown":true}`
+
+        POST /nodeState?name=%s
+
+    The 'name' parameter is the node name in the topology, e.g. "animal.air.eagle".
+
+
+- Get node state:
+
+        GET /nodeState?name=%s
+
+
+- Start a proxy:
+
+        POST /proxy?clientName=%s&proxyName=%s&proxyPort=%s&originAddr=%s
+
+    'clientName' defines where the client process is located in the topology.
+    'proxyName' defines where the proxy is located in the topology.
+    'proxyPort' will be opened and accepts incoming connection.
+    'originAddr' is the origin server address for the proxy, it can be an address in another machine,
+    eg. `192.168.1.100:12345`, so if you can not run the origin server on your localhost, you can proxy it.
+
+
+- Stop a proxy:
+
+        DELETE /proxy?proxyPort=%s
+
+
+- Get dial state from a client to server.
+
+        GET /dialState?clientName={clientName}&serverPort={serverPort}
+
+    The response is a json object like  `{"Latency":10000000,"OK":true}`
+
+
+- Get the current connection state after that connection has been created.
+
+        GET /connState?clientPort={clientPort}&serverPort={serverPort}
+
+Performance
+============
+Stadis adds an extra layer on top of tcp connection, the throughput is greatly decreased.
+On my laptop, a proxy connection with 1ms latency gets about 30MB/s throughput.
+I think it is sufficient for most of applications for testing purpose.
+Higher latency gets lower throughput which is pretty much the way raw connections work.
+
+LICENSE
+========
+The MIT License