You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+41-31Lines changed: 41 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,6 @@
1
1
# Arc
2
2
3
-
Arc is a simple, modular API Gateway that sits between a client and an [ElasticSearch](https://elastic.co) cluster. It acts as a reverse proxy, routing requests from clients to services. Arc is extended through plugins, which provide extra functionality and services beyond the ElasticSearch's RESTful API. It can perform various cross-cutting tasks such as basic authentication, logging, rate-limiting, source/referers whitelisting, analytics etc. These functionalities can clearly be extended by adding a plugin encapsulating a desired functionality. It also provides some useful abstractions that helps in managing and controlling the access
4
-
to ElasticSearch's RESTful API.
3
+
Arc is an API Gateway that sits between a client and an [ElasticSearch](https://elastic.co) cluster. It acts as a reverse proxy, routing requests from clients to services. Arc is extended through plugins, which provide extra functionality and services beyond the ElasticSearch's RESTful API. It can perform various cross-cutting tasks such as basic authentication, Role Based Access Control (using JWTs), logging, rate-limiting, source/referers whitelisting, analytics etc. These functionalities can clearly be extended by adding a plugin encapsulating a desired functionality. It also provides some useful abstractions that helps in managing and controlling the access to ElasticSearch's RESTful API.
5
4
6
5
## Table of contents
7
6
-[Overview](#overview)
@@ -15,10 +14,7 @@ to ElasticSearch's RESTful API.
15
14
## Overview
16
15
17
16
When Arc is deployed, every client request being made to the Elasticsearch
18
-
will hit Arc first and then be proxied to the Elasticsearch cluster. In between requests and responses, Arc
19
-
may execute the installed plugins, essentially extending the Elasticsearch API feature set. Arc effectively
20
-
becomes an entry point for every API request made to Elasticsearch. Arc can be used and deployed against any
21
-
Elasticsearch cluster (locally and hosted as provided by [Appbase.io](https://appbase.io)).
17
+
will hit Arc first and then be proxied to the Elasticsearch cluster. In between requests and responses, Arc may execute the installed plugins, essentially extending the Elasticsearch API feature set. Arc effectively becomes an entry point for every API request made to Elasticsearch. Arc can be used and deployed against any Elasticsearch cluster (locally and hosted as provided by [Appbase.io](https://appbase.io)).
22
18
23
19
```
24
20
.------------------------------------------.
@@ -50,6 +46,7 @@ Elasticsearch cluster (locally and hosted as provided by [Appbase.io](https://ap
50
46
## Installation
51
47
52
48
### Running it
49
+
53
50
In order to run arc, you'll require an Elasticsearch node. There are multiple ways you can [setup an Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/setup.html), either locally or remotely. We, however, are delineating the steps for local setup of a single node Elasticsearch via it's Docker image.
54
51
55
52
**Note**: The steps described here assumes a [docker](https://docs.docker.com/install/) installation on the system.
@@ -80,60 +77,73 @@ You can build the binary locally by executing the following command from the pro
80
77
81
78
This produces an executable & plugin libraries in the root project directory. To start the Arc server, run:
82
79
83
-
./build/arc --log=stdout --env=config/manual.env
80
+
```bash
81
+
./build/arc --env=config/manual.env --log=info
82
+
```
84
83
85
84
Alternatively, you could execute the following commands to start the server without producing an executable, (but still produce the plugin libraries):
86
85
87
86
make plugins
88
-
go run main.go --log=stdout --env=config/manual.env
87
+
go run main.go --env=config/manual.env
88
+
89
+
90
+
**Note**: Running the executable assumes an active Elasticsearch upstream whose URL is provided in the `.env` file.
89
91
90
-
**Note**: Running the executable assumes an active Elasticsearch connection whose url is to be provided in the `.env` file. manual.env configures it to be the localhost.
92
+
### Logging
93
+
Define the run time flag (`log`) to change the default log mode, the possible options are:
94
+
95
+
#### debug
96
+
Most verbose, use this to get logs for elasticsearch interactions.
97
+
#### info
98
+
Prints the basic information
99
+
#### error (default)
100
+
Only log the errors
91
101
92
102
#### TLS Support
93
103
94
-
You can optionally start arc to serve https requests instead of http requests using the flag https.
95
-
You also need to provide the server key & certificate file location through the environment file.
96
-
manual.env is configured to use demo server key & certificates, which work for localhost.
97
-
go run main.go --log=stdout --env=config/manual.env --https
104
+
You can optionally start arc to serve https requests instead of http requests using the flag https. You also need to provide the server key & certificate file location through the environment file. `config/manual.env` is configured to use demo server key & certificates, which work for localhost.
105
+
106
+
```bash
107
+
go run main.go --log=info --env=config/manual.env --https
108
+
```
98
109
99
-
If you wish to manually test TLS support at localhost,
100
-
curl needs to be also passed an extra parameter providing the cacert, in this case.
110
+
If you wish to manually test TLS support at localhost, curl needs to be also passed an extra parameter providing the cacert, in this case.
If you wish to test loading JWT Key through HTTP, you can use the following commands to start a HTTP
106
-
server serving the key
118
+
If you wish to test loading JWT Key through HTTP, you can use the following commands to start a HTTP server serving the key
119
+
```bash
107
120
cd sample
108
121
python -m SimpleHTTPServer 8500
109
-
122
+
```
110
123
Then start arc using the command:
111
-
go run main.go --log=stdout --env=config/manual-http-jwt.env
124
+
```bash
125
+
go run main.go --log=info --env=config/manual-http-jwt.env
126
+
```
127
+
128
+
Arc also exposes an API endpoint to set the key at runtime, so this need not be set initially.
112
129
113
130
#### Run Tests
114
131
115
-
Currently, tests are WIP and implemented for authand logs modules. You can run tests using:
132
+
Currently, tests are implemented for auth, permissions, users and billing modules. You can run tests using:
116
133
117
134
go test ./...
118
135
119
136
### Implementation
120
137
121
-
The functionality in Arc can extended via plugins. An Arc plugin can be considered as a service in itself; it can have its
122
-
own set of routes that it handles (keeping in mind it doesn't overlap with existing routes of other plugins), its own chain of
123
-
middleware and more importantly its own database it intends to interact with (in our case it is Elasticsearch). For example, one
124
-
can easily have multiple plugins providing specific services that interact with more than one database. The plugin is responsible for its own request lifecycle in this case.
138
+
The functionality in Arc can extended via plugins. An Arc plugin can be considered as a service in itself; it can have its own set of routes that it handles (keeping in mind it doesn't overlap with existing routes of other plugins), its own chain of middleware and more importantly its own database it intends to interact with (in our case it is Elasticsearch). For example, one can easily have multiple plugins providing specific services that interact with more than one database. The plugin is responsible for its own request lifecycle in this case.
125
139
126
-
However, it is not necessary for a plugin to define a set of routes for a service. A plugin can easily be a middleware
127
-
that can be used by other plugins with no new defined routes whatsoever. A middleware can either interact with a database or
128
-
not is an implementation choice, but the important point here is that a plugin can be used by other plugins as long as it
129
-
doesn't end up being a cyclic dependency.
140
+
However, it is not necessary for a plugin to define a set of routes for a service. A plugin can easily be a middleware that can be used by other plugins with no new defined routes whatsoever. A middleware can either interact with a database or not is an implementation choice, but the important point here is that a plugin can be used by other plugins as long as it doesn't end up being a cyclic dependency.
130
141
131
142
Each plugin is structured in a particular way for brevity. Refer to the plugin [docs](https://github.com/appbaseio/arc/blob/master/docs/plugins.md) which describes a basic plugin implementation.
132
143
133
144
### Abstractions
134
145
135
-
Since every request made to Elasticsearch hits Arc first, it becomes beneficial to provide a set of abstractions that allows
136
-
the client to define control over the Elasticsearch RESTful API and Arc's functionality. Arc provides several essential abstractions that are required in order to interact with Elasticsearch and Arc itself.
146
+
Since every request made to Elasticsearch hits Arc first, it becomes beneficial to provide a set of abstractions that allows the client to define control over the Elasticsearch RESTful API and Arc's functionality. Arc provides several essential abstractions that are required in order to interact with Elasticsearch and Arc itself.
137
147
138
148
## Available Plugins
139
149
@@ -153,7 +163,7 @@ In order to interact with Arc, the client must define a `User`. A `User` encapsu
153
163
154
164
### Permission
155
165
156
-
A `User` grants a `Permission` to a certain `User`, predefining its capabilities, in order to access Elasticsearch's RESTful API. Permissions serve as an entrypoint for accessing the Elasticsearch API and has a fixed *time-to-live* unlike a user, after which it will no longer be operational. A `User` is always in charge of the `Permission`it creates.
166
+
A `User` grants a `Permission` to a certain `User`, predefining its capabilities in order to access Elasticsearch's RESTful API. Permissions serve as an entry point for accessing the Elasticsearch API and has a fixed *time-to-live* unlike a user, after which it will no longer be operational. A `User` is always in charge of the `Permission`they create.
157
167
158
168
-`username`: an auto generated username that uniquely identifies the permission
159
169
-`password`: an auto generated password that verifies the identity of the permission
0 commit comments