plank

README

Plank

What is Plank?

Plank is just enough of a platform to build whatever you want on top. It is a small yet powerful Golang server that can serve static contents, single page applications, create and expose microservices over REST endpoints or WebSocket via a built-in STOMP broker, or even interact directly with other message brokers such as RabbitMQ. All this is done in a consistent and easy to follow manner powered by Transport Event Bus.

Writing a service for a Plank server is in a way similar to writing a Spring Boot Component or Service, because a lot of tedious plumbing work is already done for you such as creating an instance of a service and wiring it up with HTTP endpoints using routers etc. Just by following the API you can easily stand up a service, apply any kinds of middleware your application logic calls for, and do all these dynamically while in runtime, meaning you can conditionally apply a filter for certain REST endpoints, stand up a new service on demand, or even spawn yet another whole new instance of Plank at a different endpoint.

All features are cleanly exposed as public API and modules and, combined with the power of Golang's concurrency model using channels, the Transport Event Bus allows creating a clean application architecture, with straightforward and easy to follow logic.

Detailed tutorials and examples are currently in progress and will be made public on the Transport GitHub page. Some topics that will initially be covered are:

• Writing a simple service and interacting with it over REST and WebSocket
• Service lifecycle hooks
• Middleware management (for REST bridged services)
• Concept of local bus channel and galactic bus channel
• Communicating between Plank instances using the built-in STOMP broker
• Securing your REST and WebSocket endpoints using Auth Provider Manager

Hello world

How to build Plank

First things first, you'll need Golang SDK of at least version 1.16 because it uses a built-in package that was added as of 1.16. Once you made sure your Golang version is at least 1.16, follow the commands below:

# get all dependencies
go get ./...

# To build against your operating system
go run build.go

# or, to build against a specific operating system
BUILD_OS=darwin|linux|windows go run build.go

Once successfully built, plank binary will be ready under build/.

Generate a self signed certificate

Plank can run in non-HTTPS mode but it's generally a good idea to always do development in a similar environment where you'll be serving your audience in public internet (or even intranet). Plank repository comes with a handy utility script that can generate a pair of server certificate and its matching private key at scripts/create-selfsigned-cert.sh. Simply run it in a POSIX shell like below. (requires openssl library to be available):

# generate a pair of x509 certificate and private key files
./scripts/generate-selfsigned-cert.sh

# cert/fullchain.pem is your certificate and cert/server.key its matching private key
ls -la cert/

The real Hello World part

Now we're ready to start the application. To kick off the server using the demo app you have built above, type the following and you'll see something like this:

./build/plank start-server --config-file config.json

 ______ __      ______  __   __  __  __    
/\  == /\ \    /\  __ \/\ "-.\ \/\ \/ /    
\ \  _-\ \ \___\ \  __ \ \ \-.  \ \  _"-.  
 \ \_\  \ \_____\ \_\ \_\ \_\\"\_\ \_\ \_\ 
  \/_/   \/_____/\/_/\/_/\/_/ \/_/\/_/\/_/ 
                                           
Host			localhost
Port			30080
Fabric endpoint		/ws
SPA endpoint		/public
SPA static assets	/assets
Health endpoint		/health
Prometheus endpoint	/prometheus
...
time="2021-08-17T13:28:15-07:00" level=info msg="Service '*services.StockTickerService' initialized successfully" fileName=initialize.go goroutine=44 package=server
time="2021-08-17T13:28:15-07:00" level=info msg="Service channel 'stock-ticker-service' is now bridged to a REST endpoint /rest/stock-ticker/{symbol} (GET)\n" fileName=server.go goroutine=44 package=server
time="2021-08-17T13:28:15-07:00" level=info msg="Starting Fabric broker at localhost:30080/ws" fileName=server.go goroutine=1 package=server
time="2021-08-17T13:28:15-07:00" level=info msg="Starting HTTP server at localhost:30080 with TLS" fileName=server.go goroutine=3 package=server

Now, open your browser and navigate to https://localhost:30080/rest/stock-ticker/VMW (or type curl -k https://localhost:30080/rest/stock-ticker/VMW in Terminal if you prefer CLI), and accept the self-signed certificate warning. You will be served a page that shows the latest stock price for VMware, Inc. Try and swap out VMW with another symbol of your choice to further test it out!

NOTE: The sample service is using a loosely gated third party API which imposes a substantial limit on how many calls you can make per minute and per day in return for making the service free to all.

NOTE: If you navigate to the root at https://localhost:30080, you'll be greeted with a 404! This is an expected behavior, as the demo app does not serve anything at root /, but we will consider changing the default 404 screen to something that is informational or more appealing at least.

All supported flags and usages

Long flag	Short flag	Default value	Required	Description
--hostname	-n	localhost	false	Hostname where Plank is to be served. Also reads from $PLANK_SERVER_HOSTNAME environment variable
--port	-p	30080	false	Port where Plank is to be served. Also reads from $PLANK_SERVER_PORT environment variable
--rootdir	-r		false	Root directory for the server. Also reads from $PLANK_SERVER_ROOTDIR environment variable
--static	-s	-	false	Path to a location where static files will be served. Can be used multiple times
--no-fabric-broker	-	false	false	Do not start Fabric broker
--fabric-endpoint	-	/fabric	false	Fabric broker endpoint (ignored if --no-fabric-broker is present)
--topic-prefix	-	/topic	false	Topic prefix for Fabric broker (ignored if --no-fabric-broker is present)
--queue-prefix	-	/queue	false	Queue prefix for Fabric broker (ignored if --no-fabric-broker is present)
--request-prefix	-	/pub	false	Application request prefix for Fabric broker (ignored if --no-fabric-broker is present)
--request-queue-prefix	-	/pub/queue	false	Application request queue prefix for Fabric broker (ignored if --no-fabric-broker is present)
--shutdown-timeout	-	5	false	Graceful server shutdown timeout in minutes
--output-log	-l	stdout	false	File to output platform logs to
--access-log	-l	stdout	false	File to output HTTP server access logs to
--error-log	-l	stderr	false	File to output HTTP server error logs to
--debug	-d	false	false	Debug mode
--no-banner	-b	false	false	Do not print Plank banner at startup
--prometheus	-	false	false	Enable Prometheus at /prometheus for metrics
--rest-bridge-timeout	-	1	false	Time in minutes before a REST endpoint for a service request to timeout

Examples are as follows:

# Start a server with all options set to default values
./plank start-server

# Start a server with a custom hostname and at port 8080 without Fabric (WebSocket) broker
./plank start-server --no-fabric-broker --hostname my-app.io --port 8080

# Start a server with a 10 minute graceful shutdown timeout
# NOTE: this is useful when you run a service that takes a significant amount of time or might even hang while shutting down 
./plank start-server --shutdown-timeout 10

# Start a server with platform server logs printing to stdout and access/error logs to their respective files
./plank start-server --access-log server-access-$(date +%m%d%y).log --error-log server-error-$(date +%m%d%y).log

# Start a server with debug outputs enabled
./plank start-server -d

# Start a server without splash banner
./plank start-server --no-banner

# Start a server with Prometheus enabled at /prometheus
./plank start-server --prometheus

# Start a server with static path served at `/static` for folder `static`
./plank start-server --static static 

# Start a server with static paths served at `/static` for folder `static` and
# at `/public` for folder `public-contents`
./plank start-server --static static --static public-contents:/public

# Start a server with a JSON configuration file
./plank start-server --config-file config.json

Advanced topics (WIP. Coming soon)

OAuth2 Client

Plank supports seamless out of the box OAuth 2.0 client that support a few OAuth flows. such as authorization code grant for web applications and client credentials grant for server-to-server applications. See below for a detailed guide for each flow.

Authorization Code flow

You'll choose this authentication flow when the Plank server acts as an intermediary that exchanges the authorization code returned from the authorization server for an access token. During this process you will be redirected to the identity provider's page like Google where you are asked to confirm the type of 3rd party application and its scope of actions it will perform on your behalf and will be taken back to the application after successful authorization.

Client Credentials flow

You'll choose this authentication flow when the Plank server needs to directly communicate with another backend service. This will not require user's consent like you would be redirected to Google's page where you confirm the type of application requesting your consent for the scope of actions it will perform on your behalf. not requiring any interactions from the user. You will need to create an OAuth 2.0 Client with client_credentials grant before following the steps below to implement the authentication flow.