acebase-server 1.6.1 → 1.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +55 -37
- package/package.json +6 -4
- package/src/acebase-server.js +165 -167
- package/src/cluster.js +33 -34
- package/src/index.d.ts +25 -1
- package/src/routes/docs.js +90 -0
- package/src/start.js +14 -4
- package/src/ts/routes/auth-change-password.yaml +75 -0
- package/src/ts/routes/auth-delete.yaml +77 -0
- package/src/ts/routes/auth-forgot-password.yaml +49 -0
- package/src/ts/routes/auth-reset-password.yaml +53 -0
- package/src/ts/routes/auth-signin.yaml +129 -0
- package/src/ts/routes/auth-signout.yaml +45 -0
- package/src/ts/routes/auth-signup.yaml +120 -0
- package/src/ts/routes/auth-state.yaml +28 -0
- package/src/ts/routes/auth-update.yaml +131 -0
- package/src/ts/routes/auth-verify-email.yaml +52 -0
- package/src/ts/routes/docs.ts +93 -0
- package/src/webmanager/index.html +1 -1
- package/src/webmanager/index.js +1 -1
package/README.md
CHANGED
|
@@ -41,6 +41,23 @@ const server = new AceBaseServer(dbname, settings);
|
|
|
41
41
|
|
|
42
42
|
You can either pass ```certPath``` and ```keyPath```, or ```pfxPath``` and ```passphrase``` - depending on the type of certificate files you have.
|
|
43
43
|
|
|
44
|
+
### Enable transaction logging
|
|
45
|
+
(NEW, BETA)
|
|
46
|
+
|
|
47
|
+
AceBase now supports transaction logging to facilitate sophisticated synchronization options and custom data recovery. Using cursors that indicate certain points in time, this allows for fast and easy synchronization of data between an AceBase server and multiple clients, or other server instances. This functionality is currently in BETA stage and will be tested extensively in the coming weeks.
|
|
48
|
+
|
|
49
|
+
To enable transaction logging on your database, add the `transactions` setting:
|
|
50
|
+
```js
|
|
51
|
+
const server = new AceBaseServer(dbname, {
|
|
52
|
+
host: 'localhost', port: 443,
|
|
53
|
+
transactions: {
|
|
54
|
+
log: true, // Enable
|
|
55
|
+
maxAge: 30, // Keep logs of last 30 days
|
|
56
|
+
noWait: false // Data changes wait for log to be written
|
|
57
|
+
}
|
|
58
|
+
};
|
|
59
|
+
```
|
|
60
|
+
|
|
44
61
|
### Enable authentication
|
|
45
62
|
|
|
46
63
|
Authentication settings determine who is allowed access to your server. By enabling authentication, the server will allow users to sign in (and signup) and authorization rules to be defined for data being read/written to the database.
|
|
@@ -58,22 +75,22 @@ const settings = {
|
|
|
58
75
|
}
|
|
59
76
|
```
|
|
60
77
|
|
|
61
|
-
The following
|
|
62
|
-
-
|
|
63
|
-
-
|
|
64
|
-
-
|
|
65
|
-
-
|
|
78
|
+
The following `authentication` settings are available:
|
|
79
|
+
- `enabled`: whether to enable user authentication (default: `true`)
|
|
80
|
+
- `allowUserSignup`: whether users can sign up for an account themselves, or if the admin has to (default: `false`)
|
|
81
|
+
- `defaultAccessRule`: default authorization rule for read/write operations. Either `deny`, `allow` or `auth`. The first time the server is launched with authentication enabled, it will create a *rules.json* file that contains this access rule for any path. `deny` will deny all users (except admin) read/write access, `allow` will grant access to anyone, `auth` will grant access only to authenticated users (default: `auth`)
|
|
82
|
+
- `defaultAdminPassword`: supply a default password for the admin account that will be used when it is created. If you do not supply this, a generated password will be used instead and displayed only once in the console output.
|
|
66
83
|
|
|
67
84
|
### Setup authorization rules
|
|
68
85
|
|
|
69
|
-
If you enabled authentication, you can also define access rules for your data. Using rules, you can allow or deny specific (or anonymous) users read and/or write access to your data. These rules are identical to those used by [Firebase](https://firebase.google.com/docs/database/security/) (Note: ".read" and ".write" only, ".validate" might be implemented in the future, ".schema" implemented as alternative) and are saved in a file called _rules.json_ in your database directory. The default rules written to the file are determined by the
|
|
86
|
+
If you enabled authentication, you can also define access rules for your data. Using rules, you can allow or deny specific (or anonymous) users read and/or write access to your data. These rules are identical to those used by [Firebase](https://firebase.google.com/docs/database/security/) (Note: ".read" and ".write" only, ".validate" might be implemented in the future, ".schema" implemented as alternative) and are saved in a file called _rules.json_ in your database directory. The default rules written to the file are determined by the `defaultAccessRule` authentication setting at the first server launch with `authentication` enabled.
|
|
70
87
|
|
|
71
|
-
The default _rules.json_ file content is based on the value of the
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
88
|
+
The default _rules.json_ file content is based on the value of the `defaultAccessRule` setting, possible values are:
|
|
89
|
+
* `"auth"`: Only allow authenticated users read/write access to the database
|
|
90
|
+
* `"allow"`: Allow anyone (including anonymous users) read/write access to the database
|
|
91
|
+
* `"deny"`: Deny anyone (except admin user) read/write access to the database
|
|
75
92
|
|
|
76
|
-
When
|
|
93
|
+
When `defaultAccessRule: "auth"` is used, it will generate the following _rules.json_ file:
|
|
77
94
|
```json
|
|
78
95
|
{
|
|
79
96
|
"rules": {
|
|
@@ -83,7 +100,7 @@ When ```defaultAccessRule: "auth"``` is used, it will generate the following _ru
|
|
|
83
100
|
}
|
|
84
101
|
```
|
|
85
102
|
|
|
86
|
-
When
|
|
103
|
+
When `"allow"` or `"deny"` is used, the `".read"` and `".write"` properties will be set to `true` or `false` respectively.
|
|
87
104
|
|
|
88
105
|
If you want to further restrict what data users can access and/or write to (RECOMMENDED!), you could edit the file as such, granting users read/write access to their own user node:
|
|
89
106
|
```json
|
|
@@ -117,8 +134,8 @@ NOTE: Just like Firebase, access is denied by default when no rule is found for
|
|
|
117
134
|
```
|
|
118
135
|
Above rules enforces:
|
|
119
136
|
* No read or write access to the root node or any child for anyone. (No rule has been set for those nodes, access will be denied)
|
|
120
|
-
* Read access to all reviews for specific shops ('shop_reviews/shop1', 'shop_reviews/shop2') for anyone, including unauthenticated clients (
|
|
121
|
-
* Write access to an authenticated user's own review for any shop. (
|
|
137
|
+
* Read access to all reviews for specific shops ('shop_reviews/shop1', 'shop_reviews/shop2') for anyone, including unauthenticated clients (`".read"` rule is set to `true`)
|
|
138
|
+
* Write access to an authenticated user's own review for any shop. (`".write"` rule is set to `"auth.uid === $uid"`)
|
|
122
139
|
|
|
123
140
|
### Schema validation
|
|
124
141
|
|
|
@@ -128,7 +145,7 @@ There are 2 ways to can add schemas:
|
|
|
128
145
|
- In your `rules.json` file, see below.
|
|
129
146
|
- Programmatically through `db.schema.set`. See the [AceBase documentation](https://github.com/appy-one/acebase#adding-schemas-to-enforce-data-rules) for more info.
|
|
130
147
|
|
|
131
|
-
To ensure all users have a
|
|
148
|
+
To ensure all users have a `name` (string), `email` (string) and `language` (either Dutch, English, German, French or Spanish), optionally a `birthdate` (Date) and `address` (custom object definition), add the following to your _rules.json_ file:
|
|
132
149
|
```json
|
|
133
150
|
{
|
|
134
151
|
"rules": {
|
|
@@ -197,11 +214,11 @@ You can also decide to split the schema up into multiple levels:
|
|
|
197
214
|
|
|
198
215
|
And, if you prefer, schema definitions can be defined as strings instead:
|
|
199
216
|
```json
|
|
200
|
-
|
|
217
|
+
{
|
|
201
218
|
"address": {
|
|
202
219
|
".schema": "{ street: string, city: string, country: string, geo?: { lat: number, lon: number } }"
|
|
203
220
|
}
|
|
204
|
-
|
|
221
|
+
}
|
|
205
222
|
```
|
|
206
223
|
|
|
207
224
|
## Sending user e-mails [NEW]
|
|
@@ -225,39 +242,36 @@ function sendRequestedEmail(request) {
|
|
|
225
242
|
}
|
|
226
243
|
```
|
|
227
244
|
|
|
228
|
-
Any links you would add to the e-mails you send out should point to your own website/app, where you would handle account verification / password resets through an
|
|
245
|
+
Any links you would add to the e-mails you send out should point to your own website/app, where you would handle account verification / password resets through an `AceBaseClient` connected to your server:
|
|
229
246
|
|
|
230
|
-
```
|
|
247
|
+
```js
|
|
231
248
|
const resetCode = 'weydgaed7gjsdhfjadbsfadsfasq3w7dtuqwebd'; // eg from your_reset_url?code=weydga...
|
|
232
249
|
const newPassword = 'MyNewPassword'; // from user input on your page
|
|
233
|
-
|
|
234
|
-
.
|
|
250
|
+
try {
|
|
251
|
+
await client.auth.resetPassword(resetCode, newPassword);
|
|
235
252
|
// User can now sign in with their new password
|
|
236
|
-
}
|
|
237
|
-
|
|
253
|
+
}
|
|
254
|
+
catch(err) {
|
|
238
255
|
// Something went wrong
|
|
239
|
-
}
|
|
256
|
+
}
|
|
240
257
|
```
|
|
241
258
|
|
|
242
259
|
OR, if you have direct access to your AceBaseServer instance from your website:
|
|
243
260
|
|
|
244
261
|
```javascript
|
|
245
|
-
server.resetPassword(req.ip, resetCode, newPassword)
|
|
246
|
-
.then(() => { ... });
|
|
262
|
+
await server.resetPassword(req.ip, resetCode, newPassword);
|
|
247
263
|
```
|
|
248
264
|
|
|
249
265
|
To verify a user's email address:
|
|
250
266
|
```javascript
|
|
251
267
|
const verificationCode = 'weydgaed7gjsdhfjadbsfadsfasq3w7dtuqwebd'; // eg from your_verify_url?code=weydga...
|
|
252
|
-
client.auth.verifyEmailAddress(verificationCode)
|
|
253
|
-
.then(() => { ... })
|
|
268
|
+
await client.auth.verifyEmailAddress(verificationCode);
|
|
254
269
|
```
|
|
255
270
|
|
|
256
271
|
OR, directly on your server:
|
|
257
272
|
|
|
258
273
|
```javascript
|
|
259
|
-
server.verifyEmailAddress(req.ip, verificationCode)
|
|
260
|
-
.then(() => { ... });
|
|
274
|
+
await server.verifyEmailAddress(req.ip, verificationCode);
|
|
261
275
|
```
|
|
262
276
|
|
|
263
277
|
### E-mail request examples
|
|
@@ -317,11 +331,11 @@ Request type *user_reset_password_success*:
|
|
|
317
331
|
|
|
318
332
|
You can enable users to sign into your app through a third party login provider, such as Facebook, Google, Twitter etc. To enable this, follow these steps for each provider:
|
|
319
333
|
|
|
320
|
-
* First, get
|
|
334
|
+
* First, get `client_id` and `client_secret` API keys from the auth providers' developer environment. This will allow your app to use with the provider's auth API.
|
|
321
335
|
|
|
322
|
-
* Most OAuth providers restrict authentication callback uri's to a predefined set of uris, so make sure you add AceBase's callback URL in the provider's API settings:
|
|
336
|
+
* Most OAuth providers restrict authentication callback uri's to a predefined set of uris, so make sure you add AceBase's callback URL in the provider's API settings: `"https://your.acebase.server/oauth2/dbname/signin"` (replace hostname and dbname to your server Url)
|
|
323
337
|
|
|
324
|
-
* Then, add your API keys to your
|
|
338
|
+
* Then, add your API keys to your `AceBaseServer` config with `configAuthProvider`:
|
|
325
339
|
|
|
326
340
|
```javascript
|
|
327
341
|
server.configAuthProvider('facebook', { client_id: '[your fb app_id]', client_secret: '[your fb app_secret]', scopes: [/* Any additional scopes, such as 'user_birthday' */] });
|
|
@@ -347,7 +361,7 @@ client.auth.finishAuthProviderSignIn(callbackResult)
|
|
|
347
361
|
})
|
|
348
362
|
```
|
|
349
363
|
|
|
350
|
-
The
|
|
364
|
+
The `result` object will also contain the provider's `access_token` and `refresh_token` in case you want to make custom calls to the provider's API. If you want to keep the provider's access_token active, you will have to call `client.auth.refreshAuthProviderToken` before it expires:
|
|
351
365
|
|
|
352
366
|
```javascript
|
|
353
367
|
const keepAlive = (provider) => {
|
|
@@ -373,13 +387,13 @@ Currently implemented auth providers are:
|
|
|
373
387
|
* Facebook*
|
|
374
388
|
* Spotify
|
|
375
389
|
|
|
376
|
-
*NOTE: Facebook access tokens are short-lived by default, but will be exchanged for a long-lived (60 day) access token upon refresh. If you need to keep the Facebook access token active, execute
|
|
390
|
+
*NOTE: Facebook access tokens are short-lived by default, but will be exchanged for a long-lived (60 day) access token upon refresh. If you need to keep the Facebook access token active, execute `refreshAuthProviderToken` immediately after `finishAuthProviderSignIn`, and keep refreshing every time the user starts your app. Once a Facebook access token has expired, it cannot be refreshed and the user will have to sign in again.
|
|
377
391
|
|
|
378
392
|
## Add cloud functions to handle data changes
|
|
379
393
|
|
|
380
394
|
You can add "cloud functions" to perform custom tasks upon data changes. You can do this in 2 ways:
|
|
381
395
|
|
|
382
|
-
* In the same process you are running your
|
|
396
|
+
* In the same process you are running your `AceBaseServer` (requires server v1.1+). Make sure you run cpu heavy code in a separate worker thread to keep the server thread available for core tasks:
|
|
383
397
|
```js
|
|
384
398
|
const server = new AceBaseServer(dbname, settings);
|
|
385
399
|
await server.ready();
|
|
@@ -411,7 +425,7 @@ db.ref('uploads/images').on('child_added', async snap => {
|
|
|
411
425
|
|
|
412
426
|
## Extending the server API
|
|
413
427
|
|
|
414
|
-
You can add your own custom API functions to the server with the
|
|
428
|
+
You can add your own custom API functions to the server with the `server.extend(method, path, handler)` method:
|
|
415
429
|
|
|
416
430
|
```javascript
|
|
417
431
|
const server = new AceBaseServer(...);
|
|
@@ -459,6 +473,10 @@ client.callExtension('post', 'quotes/add', {
|
|
|
459
473
|
});
|
|
460
474
|
```
|
|
461
475
|
|
|
476
|
+
## Running in a cluster
|
|
477
|
+
|
|
478
|
+
It is possible to run your *AceBaseServer* in a cluster so you can utilize more than just the 1 CPU a Node.js application typically uses. To make sure all instances can read and write to the same database files safely they will have to be able to communicate with each other. This is done using a technique called interprocess communication (IPC). Node.js' built-in cluster functionality provides IPC channels to communicate between master and worker processes, but if you want to run a `pm2` cluster or want multiple instances running in the cloud, you'll have to use an external IPC server. See [AceBase IPC Server](https://github.com/appy-one/acebase-ipc-server) for more information about the different clustering solutions and code examples.
|
|
479
|
+
|
|
462
480
|
## Connecting to a server
|
|
463
481
|
|
|
464
482
|
See *acebase-client* on [npm](https://www.npmjs.com/package/acebase-client) or [github](https://github.com/appy-one/acebase-client)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "acebase-server",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.9.0",
|
|
4
4
|
"description": "AceBase realtime database server (webserver endpoint to allow remote connections)",
|
|
5
5
|
"main": "./src/index.js",
|
|
6
6
|
"private": false,
|
|
@@ -44,13 +44,15 @@
|
|
|
44
44
|
"author": "Ewout Stortenbeker <me@appy.one> (http://appy.one)",
|
|
45
45
|
"license": "MIT",
|
|
46
46
|
"dependencies": {
|
|
47
|
-
"acebase": "^1.
|
|
48
|
-
"acebase-core": "^1.
|
|
47
|
+
"acebase": "^1.15.3",
|
|
48
|
+
"acebase-core": "^1.13.1",
|
|
49
49
|
"express": "^4.17.1",
|
|
50
50
|
"socket.io": "^2.4.1"
|
|
51
51
|
},
|
|
52
52
|
"devDependencies": {
|
|
53
53
|
"@types/express": "^4.17.13",
|
|
54
|
-
"@types/node": "^14.0.14"
|
|
54
|
+
"@types/node": "^14.0.14",
|
|
55
|
+
"swagger-jsdoc": "^6.1.0",
|
|
56
|
+
"swagger-ui-express": "^4.3.0"
|
|
55
57
|
}
|
|
56
58
|
}
|