1 | # Exosphere SDK
|
2 | > Rails for micro-service based cloud-native applications
|
3 |
|
4 | [![Circle CI](https://circleci.com/gh/Originate/exosphere-sdk.svg?style=shield&circle-token=fc8148ed828cc81e6ca44920672af8f773106795)](https://circleci.com/gh/Originate/exosphere-sdk)
|
5 |
|
6 | This is the command-line interface of the Exosphere SDK.
|
7 |
|
8 |
|
9 | * [SDK](documentation/sdk.md)
|
10 | * [micro services](documentation/services.md)
|
11 | * [communication](documentation/communication.md)
|
12 |
|
13 |
|
14 | ## Architecture
|
15 |
|
16 | This SDK consists of the following components:
|
17 |
|
18 | * [exo-install command](commands/install):
|
19 | Sets up a freshly cloned Exosphere application
|
20 | by running the setup scripts for each service.
|
21 |
|
22 | * [exo-run command](commands/run):
|
23 | Starts a properly set up (using `exo-install`) Exosphere application
|
24 | by launching all of its services.
|
25 |
|
26 | * [feature specs](features): written in Cucumber
|
27 |
|
28 | * [ExoComm-dev](https://github.com/Originate/exocomm-dev):
|
29 | development version of the Exosphere communication infrastructure
|
30 |
|
31 |
|
32 | ## How to use
|
33 |
|
34 | * install this SDK on your machine
|
35 |
|
36 | ```
|
37 | npm i -g exosphere-sdk
|
38 | ```
|
39 |
|
40 | * download an Exosphere application, for example
|
41 | [SpaceTweet](https://github.com/Originate/exosphere--example-app--space-tweet)
|
42 |
|
43 | * set up the application:
|
44 |
|
45 | ```
|
46 | cd <application folder>
|
47 | exo-install
|
48 | ```
|
49 |
|
50 | * start the application:
|
51 |
|
52 | ```
|
53 | exo-run
|
54 | ```
|
55 |
|
56 |
|
57 | ## Message protocol
|
58 |
|
59 | The message protocol used in this prototype
|
60 | is optimized for extreme simplicity.
|
61 | This is to encourage experimentation
|
62 | and implementations using many different languages.
|
63 |
|
64 | * ExoComm sends messages to your service
|
65 | via an HTTP POST request to
|
66 |
|
67 | ```url
|
68 | /run/<message name>
|
69 | ```
|
70 |
|
71 | * the request body
|
72 | is a JSON data structure
|
73 | with the format:
|
74 |
|
75 | ```
|
76 | {
|
77 | requestId: <the ID of this message, as a UUID>
|
78 | payload: <optional, a string, array, hash, or null>
|
79 | responseTo: <optional, the requestId of the message responded to
|
80 | }
|
81 | ```
|
82 |
|
83 | * your service
|
84 | can send replies or new outgoing messages
|
85 | via an HTTP POST request to
|
86 |
|
87 | ```url
|
88 | http://localhost:<exocomm-port>/send/<message-name>
|
89 | ```
|
90 |
|
91 | * the request body is like in incoming requests
|
92 |
|
93 |
|
94 | ## Build your own service
|
95 |
|
96 | Converting an existing service into an Exoservice requires only two steps:
|
97 | * listen at the port provided via the environment variable `EXORELAY_PORT`
|
98 | for incoming requests to
|
99 |
|
100 | ```
|
101 | /run/<message name>
|
102 | ```
|
103 |
|
104 | and understand the messages sent to your service this way
|
105 |
|
106 | * send out messages and replies via POST requests to `EXORELAY_URL`
|
107 |
|
108 | * if you do this with a lot of services,
|
109 | try to use an (or build your own) service framework like
|
110 | [Exoservice-JS](https://github.com/Originate/exoservice-js)
|
111 |
|
112 |
|
113 | ## Development
|
114 |
|
115 | see our [developer guidelines](CONTRIBUTING.md)
|
116 |
|
\ | No newline at end of file |