ferry

README

Ferry

NOTE: Ferry is a WIP project, please DO NOT use it in your project so far.

Ferry is a lightweight server framework for golang. Ferry setup connections between containers based on feature dependency. This solution provides much flexibility for user to setup extendable servers quickly.

What Ferry DO

Ferry is a server framework, and define the dev pattern to standalize server startup, connection and communicate flow. So user DO NOT need to write code for low level logic, like network connection, communicate protocol, etc, but only focus on the design and implementation for internal modules. It could make the modules more cohesive, decomposed, and general to improve the reusability.

What Ferry DO NOT do

There is no real server implementation in Ferry, even no log module. Those featured modules will not be provided by Ferry, but need user to implement based on Ferry framework.

Framework Diagram

Tech Notes

• Feature container (dock) is an independent server node, and could contain many features.
• Every feature runs within an independent routine.
• Communication between features base on channel RPC (only support sync mode so far)
• Features in different docks could communicate through the same way (RPC based on feature dependency)

Quick Start

Required

Go	>=1.12.X
GO111MODULE	on

$Install

go get github.com/muguangyi/ferry

$Example: Print "Hello Ferry!"

This example will run 3 servers: Hub, Logger and Game.

Hub Server

package main

import (
    "github.com/muguangyi/ferry"
)

func main() {
    // Call ferry.Serve to start a hub server.
    ferry.Serve("0.0.0.0:9999")
    ferry.Close()
}

Logger Server

Export ILogger interface with Print method.

package main

import (
    "log"
    "github.com/muguangyi/ferry"
)

// ILogger expose to other features.
type ILogger interface {
    Print(msg string)
}

// logger compose ferry.Feature.
type logger struct{
    ferry.Feature
}

func (l *logger) Print(msg string) {
    log.Println(msg)
}

func main() {
    // Connect hub server with dock name and ILogger feature.
    ferry.Startup("127.0.0.1:9999", "logger",
        ferry.Carry("ILogger", &logger{}, true))
    ferry.Close()
}

Game Server

package main

import (
    "github.com/muguangyi/ferry"
)

type IGame interface {
}

// game compose ferry.Feature
type game struct{
    ferry.Feature
}

// OnStart could start to fill logic code.
func (g *game) OnStart(s ferry.ISlot) {
    // Call ILogger Print function.
    s.Call("ILogger", "Print", "Hello Ferry!")
}

func main() {
    // Connect hub server with dock name and IGame feature.
    ferry.Startup("127.0.0.1:9999", "game",
        ferry.Carry("IGame", &game{}, true))
    ferry.Close()
}

Ferry supports code generation to make DEV more convenient. More information refer to Document.

Limitation (TBD)

Remember the methods on feature's export interface maybe be called through network, so DO NOT design method with arbitrary parameters, like callback function, pointer, etc.

Document

https://muguangyi.github.io/ferry.io/

Documentation

Index

• func Close()
• func Register(id string, maker interface{}) bool
• func Serve(hubAddr string, blackPorts ...int)
• func Startup(hubAddr string, dockName string, slots ...ISlot)
• type Feature
  • func (f *Feature) OnDestroy(s ISlot)
  • func (f *Feature) OnStart(s ISlot)
• type IFeature
• type IProto
• type ISlot
  • func Carry(id string, feature interface{}, discoverable bool) ISlot

Functions

func Close

func Close()

Close all containers including hub or dock.

func Register

func Register(id string, maker interface{}) bool

Register feature id with proxy maker func.

func Serve

func Serve(hubAddr string, blackPorts ...int)

Serve run a hub with addr, black list for ports to avoid allocing to docks.

func Startup

func Startup(hubAddr string, dockName string, slots ...ISlot)

Startup run a dock with target hub addr, customize dock name for tracking, and all features running in this dock.

Types

type Feature

type Feature struct {
}

Feature is base struct for all IFeature to compose

func (*Feature) OnDestroy

func (f *Feature) OnDestroy(s ISlot)

OnDestroy clean up all staff.

func (*Feature) OnStart

func (f *Feature) OnStart(s ISlot)

OnStart start feature logic, etc.

type IFeature

type IFeature interface {
	// Could start feature logic, like RPC etc.
	OnStart(s ISlot)

	// Clean up all.
	OnDestroy(s ISlot)
}

IFeature interface.

type IProto

type IProto interface {
	// Marshal proto object into writer.
	Marshal(writer io.Writer) error

	// Unmarshal reader data into proto object.
	Unmarshal(reader io.Reader) error
}

IProto presents proto object.

type ISlot

type ISlot interface {
	// Get imported feature visitor.
	Visit(name string) interface{}

	// Call method with args, and no return value.
	Call(name string, method string, args ...interface{}) error

	// Call method with args, and has return values.
	CallWithResult(name string, method string, args ...interface{}) ([]interface{}, error)

	// Set target method with timeout duration.
	SetTimeout(method string, timeout float32)
}

ISlot interface.

func Carry

func Carry(id string, feature interface{}, discoverable bool) ISlot

Carry an ISlot object with kernel feature that should implement IFeature interface.