@nicferrier/crankit

A developer tool for microservices?

crank is a tool for developing with the cranker HTTP(S) application router.

Install it like:

$ npm install -g @nicferrier/crankit

and then you can find out about it like:

$ crank help

in addition crank with no arguments will always give you a clue.

What is cranker?

cranker is a sort of service discovery tool.

A service is a small node program (or anything really) providing an HTTP API or UI.

To develop with cranker you want to:

• start a cranker router
• start the services that talk to each other or user-agents through cranker
• tell each service about the cranker endpoint so they can find each other
• connect each service to the cranker
• when any service changes then automatically restart it

And you want to do all this without any hassle.

How to develop something with crankit and cranker

If you are developing a blog with 3 services:

• blog-service
• user-service
• blog-frontend

to start a cranker dev environment, you might:

$ cd blog-service
$ crank 8080
$ crank startapp blog server.js
$ crank status
/blog blog-service/server.js running for 10 seconds
$ cd ../user-service
$ crank startapp users server.js
error - what router do you mean? specify a port like

  crank startapp <port> users server.js

$ crank startapp 8080 users server.js
$ crank status
/blog by ../blog-service/server.js on 6652 for 120 seconds
/users by server.js on 6670 for 2 seconds

How does crankit know what router to use?

crank saves a directory called .crankit in the directory in which it was started. This directory records all the information about the router running in the background and when you use a crank command without specifying a router crank tries to find this file to tell it what to do.

If you want to start something outside that directory you need

How does crankit know what port server.js is using

The crank process creates TCP ports for your programs to use and communicates them to your program through an environment variable: APP_PORT.

For example, your program, called server.js:

const express=require("express");
const app = express();
const listener = app.listen(process.env["APP_PORT"]);

can be started like this:

crank startapp blog server.js

crank starts a cranker connector process for server.js with the path blog and a free port that it has allocated and passed to your program on the APP_PORT environment variable.

Using crankit to serve directories

crankit has built in directory serving as a handy extra. Don't feel you have to use it. Making webservers is a trivial process normally and can often have value.

But if you're needing to start webservers, perhaps for 2 or 3 static directories of documentation as you develop then perhaps this is a good way.

It goes like this:

$ crankit 9001                                                   # start on port 9001
$ crankit startdir rustdoc ~/.rustup/toolchain/*/share/doc/html  # serve the rust docs
$ curl http://localhost:9001/rustdoc                             # curl from the cranker

you can startdir as many times as you like, but each one has a separate port internally, they're all internally cranked webservers.

Working with crank with bash completion

To work with crank you might want to load the completion file.

crank can help with that by sending the completion bash source code to the console for you:

If you had checked the repository out and were working without crank installed, you might:

$ source <(node crank complete)

Alternatively, if you have installed it, you could just:

$ source <(crank complete)

the shell script will warn you if crank is not a defined variable name.

A fully automated bash completion system could be achieved by putting this in your .bashrc.

Restarting everything with crankit

If you have a .crankit file you can shut down everything and restart with:

$ crank restart