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