samb

README

samb

samb offers a structured language to build RESTful HTTP APIs. samb provides syntax support for languages similar to those used to write infrastructure as code. It offers:

• A simple way to inject variables in request scope.
• Nest API routes without long path prefixes.
• Catch request runtime panics.
• Generate Go code following guidelines.
• A tested library to use samb as you wish.

Once you finish writing your code, you may then, deploy your project to your cloud provider of choice.

Editor Plugins :

• VScode
• Sublime 3

Documentation

Learn more about samb code generation : here. Scroll down to find more samples.

Install

Requirements

• samb requires Go +v1.8
• dep (Dependency management)
• $GOPATH environment variable set.

go get github.com/cheikhshift/samb/cmd/samb-cl

Starting a project

Create a new directory, then run the following command.

samb-cl -new -project=<NEW DIR PATH> <PACKAGE GO IMPORT PATH>

The command will add files in the new folder. Have a look at the files generated to give you an idea on how samb directives work. Some directives have comments further explaining their functionality.

Transpiling

Run the following command to convert your directives into Go code.

samb-cl -file=server.se -project=<NEW DIR PATH>

This will convert your directives into a Go library to handle your HTTP routes. A command will also be generated to launch your server, you can find the source code at <NEW DIR PATH>/cmd/server.

About parser

The following package is used to parse this Nginx like configuration language : github.com/recoye/config, Nginx configuration style parser with golang.

The following package is used to parse YAML : gopkg.in/yaml.v2

Additional packages

Parth : Path parsing for segment unmarshaling and slicing.

---

Tooling

Here is a list of tools that generate Go code for your SAMB projects.

samb-handler : Generate Go HTTP handlers with the specified parameters.

• Install : go get github.com/cheikhshift/samb/cmd/samb-handler
• Help : Run samb-handler -h

samb-provide: Generate and add a provider to your project. This will generate the Go source used with your provider as well.

• Install : go get github.com/cheikhshift/samb/cmd/samb-provide
• Help : Run samb-provide -h

samb-medic : Generate recover directive functions for your project.

• Install : go get github.com/cheikhshift/samb/cmd/samb-medic
• Help : Run samb-medic -h

Todo

• Provide better documentation. Checkout the wiki.
• Sublime/VSCode text plugins.
• Write package tests.
• Write tutorials/ guides.
• A command line to help with adding new handler source.
• Implement direct deployment to GCP App engine.

Samples

Find more sample projects here. Here is a sample server definition (in Nginx like language) :

server {
    host 127.0.0.1;
    port 8080;

    # Import web route definitions
    require "./endpoints.se";


    start {
    	do println("Hello");
    	do println("Hello again");
    }

    shutdown {
	# directive do will execute passed
	# golang code
    	do println("Bye");
    }  
}

In YAML:

# Go package import path of your project.
package: github.com/cheikhshift/samb-examples/yaml-example

# import providers
require: ["./providers.se"]


# Globals are exported via package 
# globals
global:
  - name: Foo
    type : bool
    # Adding comments to exported variable.
    comment: Foo decides if a process should run
    return : false
  - name: AnotherVariable
    type : bool
    return: true

server: 
  host: 127.0.0.1
  port: 8081
  # Import web route definitions
  require : ["./endpoints.yml"]

  start:
    do:
      - println("HelloWorld")
      - println("Starting...")

Sample Route (file named endpoints.se)

# Routes' definition
# Import Go packages with directive import
# For example import "net/http";
# samb source format checking.


routes {
    provide r;

    route {
	    method *;
	    # Defines route path.
	    # all sub routes have this path
	    # prepended.
	    path "/hello/";

	    # Provider variables
	    # within scope of entire 
	    # route.
	    provide w;
	    provide r;


	    go {
	    	do println("Hello");
	    	# The following commented
	    	# do directive will stop a
	    	# request :
	    	# do return;
	    }

	    route {
	    	method GET;
	    	path "Foo";

	    	go {
	    		do println("Hello");
	    	}

	    	# Handler can be any function.
	    	# Should be a function that handles the request
	    	# response. using provided variable r
		# with handler. This code will fail,
		# the referenced handler is not defined
	    	handler virtualPackage.Handle(r);
	    }


	}
}

Sample Providers

# Providers are used
# within endpoint requests.
provider {
	name r;
	type *http.Request;
    # directive return is not used here.
    # return can be used to define how your
    # provider is initialized. For example,
    # providing a variable with value "Foo"
    # : return string("Foo") 
}

provider {
	name w;
	type *http.ResponseWriter;
}

Documentation

Overview

Package samb has server-assembly's (SAMB) struct types.

Index

• func LoadSE(path string, p *Project) error
• func LoadYAML(path string, p *Project) error
• type Documentation
• type Global
• type Go
• type Project
  • func Load(path string) (*Project, error)
  • func (p *Project) GetProvider(name string) (pr Global)
  • func (p *Project) HasProvider(name string) (has bool)
  • func (p *Project) MergeWith(file *Project)
  • func (p *Project) ProcessImports()
• type Route
• type Routes
• type Server
• type Template
• type Templates

Functions

func LoadSE

func LoadSE(path string, p *Project) error

LoadSE loads .se file with SAMB directives.

func LoadYAML

func LoadYAML(path string, p *Project) error

LoadYAML loads a YAML file with SAMB directives.

Types

type Documentation

type Documentation struct {
	// Comment is used
	// with documentation
	// generation.
	Comment string
	// Alias specifies how the resource
	// should be used.
	Alias string
}

Documentation will be used to generate HTML documentation of your code.

type Global

type Global struct {
	Name, Type, Return, Comment string
}

type Go

type Go struct {
	Do []string
}

Array of Go statements to be executed.

type Project

type Project struct {
	Server          Server
	Require, Import []string
	// Provider defines the providers
	// to be used by HTTP routes.
	Provider  []Global
	Package   string
	Author    string
	Packages  []string
	Routes    Routes
	Templates Templates
	Global    []Global
}

Project has your samb

directives.

func Load

func Load(path string) (*Project, error)

Load opens a project based on the filesystem path supplied.

func (*Project) GetProvider

func (p *Project) GetProvider(name string) (pr Global)

GetProvider gets a provider from a project, based on the name passed. It is recommended to check for a provider with local function HasProvider prior to getting it.

func (*Project) HasProvider

func (p *Project) HasProvider(name string) (has bool)

HasProvider checks to see if the project has a provider with the specified name.

func (*Project) MergeWith

func (p *Project) MergeWith(file *Project)

MergeWith combines one project with the one specified as a parameter.

func (*Project) ProcessImports

func (p *Project) ProcessImports()

ProcessImports handles finding and merging imports defined by project.

type Route

type Route struct {
	Method, Path string
	// Provide is a list of
	// provider names to be used by request.
	Provide []string
	Route   []Route
	Handler string
	// Go specifies Go code
	// to be ran prior to invocation
	// of handler. This code must respect
	// the scope of a Go HTTP handler function,
	// with variables r and w in scope.
	Go  Go
	Doc Documentation
	// Strict specifies
	// if route should only be invoked
	// if the request path matches this
	// routes' path
	Strict bool
	// Require will import and nest the
	// routes from the specified SAMB sources.
	Require []string
}

Route specifies the contract needed to be met by a request, and the handler (Go code) to be executed.

type Routes

type Routes struct {
	Route   []Route
	Provide []string
	Doc     Documentation
}

Routes holds a group of HTTP routes.

type Server

type Server struct {
	Host, Key string
	Port      string
	Webroot   string
	Require   []string
	// Routes field will enable
	// route nesting.
	Routes Routes
	Start  Go
	// Functions to be invoked
	// on panic.
	Recover  Go
	Init     Go
	Shutdown Go
}

Server specifies the generated web server properties.

type Template

type Template struct {
	FilePath, Type, Name string
}

type Templates

type Templates struct {
	Template []Template
}