leveros: github.com/leveros/leveros/api Index | Files | Directories

package api

import "github.com/leveros/leveros/api"

Package api provides Lever OS libraries for both implementing Lever services in Go and invoking Lever methods, as a client.

Quick example of a Lever service implementation

$ mkdir hello
$ cd hello

server.go

package main

import (
    "fmt"
    "log"

    leverapi "github.com/leveros/leveros/api"
)

func main() {
	server, err := leverapi.NewServer()
	if err != nil {
		log.Fatalf("Error: %v\n", err)
	}
	err = server.RegisterHandlerObject(new(Handler))
	if err != nil {
		log.Fatalf("Error: %v\n", err)
	}
	server.Serve()
}

// Handler is the service handler. Its exported methods become the service's
// methods.
type Handler struct {
}

// SayHello returns a salutation for the given name.
func (*Handler) SayHello(name string) (result string, err error) {
	return fmt.Sprintf("Hello, %s!", name), nil
}

lever.json

{
    "name": "helloService",
    "description": "A hello service.",
    "entry": ["./serve"]
}

Compile and deploy

$ GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o ./serve server.go
$ lever deploy

Note the env vars for compiling for Lever OS. These need to be GOOS=linux GOARCH=amd64 CGO_ENABLED=0 even when running on Mac or Windows.

If you have problems building, you may need to reinstall Go to include cross-compilation support. On a Mac, you can achieve this with brew install go --with-cc-common.

To try it out, invoke it with the CLI:

$ lever invoke /helloService/SayHello '"world"'

"Hello, world!"

Quick example of a Lever client

package main

import (
	"log"
	"os"

	leverapi "github.com/leveros/leveros/api"
)

func main() {
    client, err := leverapi.NewClient()
    if err != nil {
		log.Fatalf("Error: %v\n", err)
	}
	client.ForceHost = os.Getenv("LEVEROS_IP_PORT")
    leverService := client.Service("dev.lever", "helloService")
    var reply string
    err = leverService.Invoke(&reply, "SayHello", "world")
    if err != nil {
        log.Printf("Error: %v\n", err)
    }
    log.Printf("%s\n", reply) // Hello, world!
}

To run this

# Without docker-machine
$ LEVEROS_IP_PORT="127.0.0.1:8080" go run client.go

# With docher-machine
$ LEVEROS_IP_PORT="$(docker-machine ip default):8080" go run client.go

Setting LEVEROS_IP_PORT is necessary so that you can invoke the dev.lever environment without adding an entry for it in /etc/hosts and setting the listen port to 80.

Index

Package Files

api.go client.go doc.go server.go stream.go

Constants

const PackageName = "api"

PackageName is the name of this package.

Variables

var (
    // OwnEnvironment is the name of the environment the current service
    // operates in. This is meant to be "" if used from outside a lever service.
    OwnEnvironment = os.Getenv("LEVEROS_ENVIRONMENT")
    // OwnService is the name of the current service. This is meant to be "" if
    // used from outside a lever service.
    OwnService = os.Getenv("LEVEROS_SERVICE")
    // OwnInstanceID is the name of the current instance. This is meant to be
    // "" if used from outside a lever service.
    OwnInstanceID = os.Getenv("LEVEROS_INSTANCE_ID")
)

func IsChanMethod Uses

func IsChanMethod(name string) bool

IsChanMethod returns true if the name represents a valid streaming method name.

type BytesError Uses

type BytesError interface {
    GetBytes() []byte
    error
}

BytesError is an error that can be represented as bytes.

type Client Uses

type Client struct {
    ForceHost string
    // contains filtered or unexported fields
}

Client is a Lever OS client. It can be used to initiate RPC's to other lever services.

func NewClient Uses

func NewClient() (*Client, error)

NewClient creates a new Lever Client.

func (*Client) InvokeChanURL Uses

func (client *Client) InvokeChanURL(
    leverURLStr string, args ...interface{}) (stream Stream, err error)

InvokeChanURL invokes a remote streaming method referenced by a Lever URL. The URL can be either absolute (remote environment) or relative (same environment). Example:

/<service>[/<resource>]/method (relative URL)

lever://<env>/<service>[/<resource>]/method (absolute URL)

func (*Client) InvokeURL Uses

func (client *Client) InvokeURL(
    replyObj interface{}, leverURLStr string, args ...interface{}) (err error)

InvokeURL invokes a remote method referenced by a Lever URL. The URL can be either absolute (remote environment) or relative (same environment). Example:

/<service>[/<resource>]/method (relative URL)

lever://<env>/<service>[/<resource>]/method (absolute URL)

func (*Client) Resource Uses

func (client *Client) Resource(
    env string, service string, resource string) *Endpoint

Resource returns an endpoint representing a Lever resource within a Lever service. If env is "" then the current environment is used (assuming you are running within a Lever instance).

func (*Client) Service Uses

func (client *Client) Service(env string, service string) *Endpoint

Service returns an endpoint representing a Lever service. If env is "" then the current environment is used (assuming you are running within a Lever instance).

type ClientStream Uses

type ClientStream struct {
    // contains filtered or unexported fields
}

ClientStream is the client Stream object that is returned when invoking a streaming RPC.

func (*ClientStream) Close Uses

func (stream *ClientStream) Close() error

Close implements the Stream interface.

func (*ClientStream) Context Uses

func (stream *ClientStream) Context() context.Context

Context implements the Stream interface.

func (*ClientStream) Receive Uses

func (stream *ClientStream) Receive(msgObj interface{}) error

Receive implements the Stream interface.

func (*ClientStream) Send Uses

func (stream *ClientStream) Send(msg interface{}) error

Send implements the Stream interface.

type Endpoint Uses

type Endpoint struct {
    // contains filtered or unexported fields
}

Endpoint represents a Lever service or a Lever resource within a service. It can be used to invoke methods remotely.

func (*Endpoint) Invoke Uses

func (endpoint *Endpoint) Invoke(
    replyObj interface{}, method string, args ...interface{}) (err error)

Invoke invokes a remote method and populates replyObj with the response if successful.

func (*Endpoint) InvokeChan Uses

func (endpoint *Endpoint) InvokeChan(
    method string, args ...interface{}) (stream Stream, err error)

InvokeChan invokes a remote streaming method. It returns a Stream object which can be used to communicate with the Lever instance in real-time.

type RemoteByteError Uses

type RemoteByteError struct {
    Err []byte
}

RemoteByteError is an error received as bytes after calling a remote method.

func (*RemoteByteError) Error Uses

func (err *RemoteByteError) Error() string

func (*RemoteByteError) GetBytes Uses

func (err *RemoteByteError) GetBytes() []byte

GetBytes returns the error as bytes.

type RemoteError Uses

type RemoteError struct {
    Err interface{}
}

RemoteError is an error received after calling a remote method.

func (*RemoteError) Error Uses

func (err *RemoteError) Error() string

type Server Uses

type Server struct {
    // contains filtered or unexported fields
}

Server is a server that handles Lever RPCs.

func NewServer Uses

func NewServer() (server *Server, err error)

NewServer creates a new Server.

func (*Server) HandleRPC Uses

func (server *Server) HandleRPC(
    ctx context.Context, rpc *core.RPC) (reply *core.RPCReply, err error)

HandleRPC is an internal method. Do not use!

func (*Server) HandleStreamingRPC Uses

func (server *Server) HandleStreamingRPC(
    grpcStream core.LeverRPC_HandleStreamingRPCServer) error

HandleStreamingRPC is an internal method. Do not use!

func (*Server) RegisterHandler Uses

func (server *Server) RegisterHandler(
    name string, handler interface{}) error

RegisterHandler registers a function to handle the method with provided name.

func (*Server) RegisterHandlerObject Uses

func (server *Server) RegisterHandlerObject(obj interface{}) error

RegisterHandlerObject registers an object to handle RPCs with method names that are the same as the methods of the provided object. Private methods are ignored.

func (*Server) Serve Uses

func (server *Server) Serve() error

Serve enters the Server's serving loop. This blocks until the server no longer serves.

func (*Server) Stop Uses

func (server *Server) Stop()

Stop stops a Server that is currently serving.

type ServerStream Uses

type ServerStream struct {
    // contains filtered or unexported fields
}

ServerStream is the server Stream object that is provided as the first parameter in a Lever channel method.

func (*ServerStream) Close Uses

func (stream *ServerStream) Close() error

Close implements the Stream interface.

func (*ServerStream) Context Uses

func (stream *ServerStream) Context() context.Context

Context implements the Stream interface.

func (*ServerStream) Receive Uses

func (stream *ServerStream) Receive(msgObj interface{}) error

Receive implements the Stream interface.

func (*ServerStream) Send Uses

func (stream *ServerStream) Send(msg interface{}) error

Send implements the Stream interface.

type Stream Uses

type Stream interface {
    // Send sends a message to the other end of the channel.
    Send(msg interface{}) error
    // Receive receives the next message from the the channel and populates
    // msgObj with it. If the other end has closed then this returns io.EOF
    // (and doesn't populate msgObj).
    Receive(msgObj interface{}) error
    // Close closes this end of the channel. This means that writing is no
    // longer possible, though receiving can continue normally until the other
    // end closes the channel itself.
    Close() error
    // Context returns the context associated with the channel.
    Context() context.Context
}

Stream is either the first parameter of a Lever channel method (server) or the return value of a streaming RPC (client). It can be used to send and receive messages related to a streaming RPC.

Directories

PathSynopsis
adminPackage admin provides convenience function for interacting with the admin service.

Package api imports 13 packages (graph) and is imported by 12 packages. Updated 2016-07-16. Refresh now. Tools for package owners.