Skip to content

Core directives

Jump to bottom
Cheikh Seck edited this page Dec 30, 2018 · 9 revisions

This page covers the core samb directives. Syntax examples will be displayed for YAML and samb (.se) files. Each directive will have a table, the table will display the directive's name, type and parent. The parent of a directive specifies where it is nested. If ROOT is specified as the parent, the directive should be placed at the root of your file.

Index

HTTP requests

The following directives are used to define RESTful HTTP APIs.

Server

Directive server is used to define a server or application (if deploying to App engine).

Directive name Type Parent
server Server ROOT

Attributes

Name Type Description
host string The hostname the server should bind to. (if not deploying to app engine)
port string The port the server should listen on. (if not deploying to app engine)
require string array Other samb route definitions to import.
start App start Event.
shutdown App stop Event.
recover Request panic Event.

YAML sample :

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

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

.SE sample :

server {
    host 127.0.0.1;
    port 8080;

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


    start {
    	do println("Hello");
    }

    shutdown {
    	do println("Bye");
    }  
}

Providers

Providers add variables to the scope of the underlying Go code handling your route. These variables should be generated by reading data from the request invoking the route. Provided variables can consist of session ids, a JWT decoder that returns a Go map of a submitted token, a data type representing user permissions etc... If you plan on implementing your own provider, use command samb-provide (within this repository) to generate provider function.

Directive name Type Parent
provider array of Global ROOT

YAML sample :

...
provider:
  - name: FooBar
    type : "*string"
    return : providerFooBar(w,r)
...

.SE sample :

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


provider {
	name FooBar;
	type *string;
	return providerFooBar(w,r);
}

Routes

Routes define a group of HTTP resources for your API. Directive route is used to define individual HTTP resources.

Directive name Type Parent
Routes Routes ROOT or Server

Route

A route defines an HTTP API resource. You can read more about route concepts here.

Directive name Type Parent
Routes Route Routes

Attributes

Name Type Description
method string Request verb/method of resource. Use * to indicate all verbs/methods.
path string HTTP path to resource. If route is nested, the path used for invocation will be prefixed by the paths of previously defined routes.
provide string array Array of the provider names to use with request.
go Go Go code to be ran prior to request handling. This can be additional logging, tracing, middleware functions etc.
route Route array Nested route.

YAML sample :

...
# SAMB endpoint declarations in YAML.
routes:
  provide: ["r","w"]
  route :
    - method : "*"
      path : /shoes/ # :ID
      go :
        do :
          - w.Header().Set("Content-Type", "application/json")
          - println(r.Method + " request to " + r.URL.Path)
      handler : HandleShoes(w, r)
...

.SE sample :

routes {
    provide w;
    
    route {
	    method *;
	    # Defines route path.
	    # all sub routes have this path
	    # prepended.
	    path "/hello/";
	    provide FooBar;
	    handler w.Write([]byte("Hello World" + *FooBar));
	}
}

Globals

A global represents a variable. A global can be used as an exported application variable or provider definition.

Directive name Type Parent
Global Global ROOT

Attributes

Name Type Description
name string Name of global.
type string Go type of variable.
return string Go code that initializes the variable. If the global is a provider, you must use a function utilizing parameters r (*http.Request) and w (http.ResponseWriter). Those parameters will be in your providers' scope on execution.

YAML sample :

...
# Globals are exported via package 
# globals
global:
  - name: Client
    type : "*mongo.Client"
    # Adding comments to exported variable.
    comment: Shared database res.
    # The following function is in exported GO
    # package globals.
    return : LoadClient()
...

.SE sample :

# Globals are exported via package 
# globals
global {
	name Prod;
	type bool;
    # Directive return specifies the 
    # value of the global variable
	return false;
}

Go

Directive Go executes declared Go code, in the order it is entered.

Directive name Type Parent
Go Global Start, Stop, Recover or Route

Attributes

Name Type Description
do string array Go statements to execute. Please be aware of the variables in scope, to prevent compile errors.

YAML sample :

...
      go :
        do :
          - w.Header().Set("Content-Type", "application/json")
          - println(r.Method + " request to " + r.URL.Path)
...

.SE sample :

	    go {
	    	do println("Hello");
	    	do println(*FooBar);
	    }

Package

Directive package is used to define the Go import path of your project.

Directive name Type Parent
Package string ROOT

YAML sample :

...
package : github.com/cheikhshift/samb
...

.SE sample :

package github.com/cheikhshift/samb;
Clone this wiki locally