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/src/index.d.ts CHANGED
@@ -74,8 +74,17 @@ declare namespace acebaseserver {
74
74
 
75
75
  /**
76
76
  * Shuts down the server. Stops listening for incoming connections, breaks current connections and closes the database.
77
+ * Is automatically executed when a "SIGINT" process event is received.
78
+ *
79
+ * Once the shutdown procedure is completed, it emits a "shutdown" event on the server instance, "acebase-server-shutdown" event on the `process`, and sends an 'acebase-server-shutdown' IPC message if Node.js clustering is used.
80
+ * These events can be handled by cluster managing code to `kill` or `exit` the process safely.
77
81
  */
78
82
  shutdown(): Promise<void>
83
+
84
+ /** Temporarily stops the server from handling incoming connections, but keeps existing connections open */
85
+ pause(): Promise<void>
86
+ /** Resumes handling incoming connections */
87
+ resume(): Promise<void>
79
88
  }
80
89
 
81
90
  interface IOAuthProviderSettings {
@@ -109,6 +118,10 @@ declare namespace acebaseserver {
109
118
  email?: AceBaseServerEmailSettings
110
119
  /** Transaction logging settings. Warning: BETA stage, do NOT use in production yet */
111
120
  transactions?: AceBaseServerTransactionLogSettings
121
+ /** IPC settings for pm2 or cloud-based clusters. BETA stage, see https://github.com/appy-one/acebase-ipc-server */
122
+ ipc?: IPCClientSettings
123
+ /** Allows overriding of default storage settings used by the database. ALPHA stage */
124
+ storage?: any
112
125
  }
113
126
 
114
127
  interface AceBaseServerHttpsSettings {
@@ -154,7 +167,18 @@ declare namespace acebaseserver {
154
167
  maxAge?: number;
155
168
  noWait?: boolean;
156
169
  }
157
-
170
+ interface IPCClientSettings {
171
+ /** IPC Server hostname. Default is "localhost" */
172
+ host?: string
173
+ /** IPC Server port */
174
+ port: number
175
+ /** IPC Server token needed to access the server. Only needed if the server does not use a token */
176
+ token?: string
177
+ /** Whether to use a secure connection to the IPC server, default is `false` */
178
+ ssl?: boolean
179
+ /** Role of the IPC Client. There can only be 1 `master`, all other need to be a `worker`. */
180
+ role: 'master'|'worker'
181
+ }
158
182
  interface AceBaseEmailRequest {
159
183
  readonly type: string
160
184
  readonly ip: string
@@ -0,0 +1,90 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const path = require("path");
4
+ const swaggerJsdoc = require("swagger-jsdoc");
5
+ const swaggerUi = require("swagger-ui-express");
6
+ // import config from '../config';
7
+ const addRoute = (app) => {
8
+ // Generate docs from all yaml files
9
+ const options = {
10
+ definition: {
11
+ openapi: '3.0.0',
12
+ info: {
13
+ title: 'AceBase Server API',
14
+ description: 'AceBase Server API',
15
+ version: '1.0.0',
16
+ contact: {
17
+ name: 'Ewout Stortenbeker',
18
+ email: 'me@appy.one'
19
+ },
20
+ },
21
+ components: {
22
+ securitySchemes: {
23
+ bearerAuth: {
24
+ type: 'http',
25
+ scheme: 'bearer',
26
+ bearerFormat: 'token' // switch to JWT in the future?
27
+ }
28
+ },
29
+ schemas: {
30
+ User: {
31
+ type: 'object',
32
+ properties: {
33
+ uid: { type: 'string', example: 'jpx0k53u0002ecr7s354c51l' },
34
+ username: { type: 'string', example: 'someuser' },
35
+ email: { type: 'string', example: 'email@domain.com' },
36
+ displayName: { type: 'string', example: 'Some User' },
37
+ picture: {
38
+ type: 'object',
39
+ properties: {
40
+ width: { type: 'number', example: 500 },
41
+ height: { type: 'number', example: 500 },
42
+ url: { type: 'string', example: 'https://profile.pic/user.jpg' }
43
+ }
44
+ },
45
+ emailVerified: { type: 'boolean', example: true },
46
+ created: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
47
+ prevSignin: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
48
+ prevSigninIp: { type: 'string', example: '127.0.0.1' },
49
+ lastSignin: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
50
+ lastSigninIp: { type: 'string', example: '127.0.0.1' },
51
+ changePassword: { type: 'boolean', example: false },
52
+ changePasswordRequested: { type: 'boolean', example: false },
53
+ changePasswordBefore: { type: 'string', example: '2022-03-09T15:38:57.361Z' },
54
+ settings: { type: 'object' }
55
+ }
56
+ },
57
+ Error: {
58
+ type: 'object',
59
+ properties: {
60
+ code: { type: 'string', description: 'error code', example: 'invalid_request' },
61
+ message: { type: 'string', description: 'The error message', example: 'Invalid request for this endpoint' }
62
+ }
63
+ },
64
+ UnexpectedError: {
65
+ type: 'object',
66
+ properties: {
67
+ code: { type: 'string', value: 'unexpected', description: 'The string `"unexpected"`' },
68
+ message: { type: 'string', description: 'The server error message' }
69
+ }
70
+ },
71
+ UnknownError: {
72
+ type: 'object',
73
+ properties: {
74
+ code: { type: 'string', value: 'unknown', description: 'The string `"unknown"`' },
75
+ message: { type: 'string', description: 'The server error message' }
76
+ }
77
+ }
78
+ }
79
+ },
80
+ security: [
81
+ // Enable bearer auth globally
82
+ { bearerAuth: [] }
83
+ ],
84
+ },
85
+ apis: [path.resolve(__dirname, '../ts/routes/*.yaml')]
86
+ };
87
+ const swaggerDocs = swaggerJsdoc(options);
88
+ app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
89
+ };
90
+ exports.default = addRoute;
package/src/start.js CHANGED
@@ -15,11 +15,21 @@ function getVariable(name, defaultValue) {
15
15
  const path = getVariable('DBPATH', '.');
16
16
  const dbname = getVariable('DBNAME', 'default');
17
17
  const host = getVariable('HOST', '0.0.0.0');
18
- const port = parseInt(getVariable('PORT', 3000));
19
- const clusterPort = parseInt(getVariable('CLUSTER_PORT', 0));
18
+ const port = +getVariable('PORT', 3000);
19
+ const ipcPort = +getVariable('IPC_PORT', 0);
20
20
  const options = { host, port, path };
21
- if (clusterPort > 0) {
22
- options.cluster = { enabled: true, port: clusterPort };
21
+ if (ipcPort > 0) {
22
+ const role = getVariable('IPC_ROLE');
23
+ if (!['master','worker'].includes(role)) {
24
+ throw new Error('IPC_ROLE must be either "master" or "worker"');
25
+ }
26
+ options.ipc = {
27
+ host: getVariable('IPC_HOST'),
28
+ port: ipcPort,
29
+ ssl: +getVariable('IPC_SSL', 0) === 1,
30
+ token: getVariable('IPC_TOKEN'),
31
+ role
32
+ };
23
33
  }
24
34
  if (+getVariable('TXLOG', 0) === 1) {
25
35
  options.transactions = {
@@ -0,0 +1,75 @@
1
+ /auth/{dbname}/change_password:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Changes a user account's password by providing the current and new passwords
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: request object
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ type: object
20
+ properties:
21
+ uid:
22
+ type: string
23
+ description: Account's uid
24
+ password:
25
+ type: string
26
+ description: Current password set on the account
27
+ new_password:
28
+ type: string
29
+ description: New password to set on the account
30
+ required:
31
+ - uid
32
+ - password
33
+ - new_password
34
+ responses:
35
+ 200:
36
+ description: If the password change is successful, returns an object with a new access token
37
+ content:
38
+ 'application/json':
39
+ schema:
40
+ type: object
41
+ properties:
42
+ access_token:
43
+ description: New access token that provides access to API calls that require authentication.
44
+ type: string
45
+ example: ewufh387f3fyubqwekrjbcqwkuiec7gq3euyfbqwkuyebqjk..
46
+ user:
47
+ $ref: '#/components/schemas/User'
48
+ 400:
49
+ description: Returns a `"400 Bad Request"` if the sent request is invalid. If the request is missing details, response is the string `"Bad Request"`. Otherwise, it's an object with `code` and `message` properties. Possible codes are `"unknown_uid"`, `"wrong_password"`, `"wrong_access_token"` (if not signed in as the user the password change was requested for)
50
+ content:
51
+ 'text/plain':
52
+ schema:
53
+ type: string
54
+ value: Bad Request
55
+ example: Bad Request
56
+ 'application/json':
57
+ schema:
58
+ $ref: '#/components/schemas/Error'
59
+ example:
60
+ code: wrong_access_token
61
+ message: "Cannot change password while signed in as other user, or with an old token"
62
+ 422:
63
+ description: New password does not meet the criteria
64
+ content:
65
+ 'text/plain':
66
+ schema:
67
+ type: string
68
+ value: "Invalid new password, must be at least 8 characters and contain a combination of numbers and letters (both lower and uppercase)"
69
+ example: "Invalid new password, must be at least 8 characters and contain a combination of numbers and letters (both lower and uppercase)"
70
+ 500:
71
+ description: An unexpected error occurred
72
+ content:
73
+ 'application/json':
74
+ schema:
75
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,77 @@
1
+ /auth/{dbname}/delete:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Deletes an existing user account
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: Account to delete
16
+ content:
17
+ 'text/plain':
18
+ schema:
19
+ type: string
20
+ value: ''
21
+ example: ''
22
+ description: Empty content to delete signed in user account
23
+ 'application/json':
24
+ schema:
25
+ type: object
26
+ properties:
27
+ uid:
28
+ type: string
29
+ description: (admin user only) to delete a specific user account, the target account `uid` must be passed with the request
30
+ example: jpx0k53u0002ecr7s354c51l
31
+ responses:
32
+ 200:
33
+ description: When delete succeeds, it returns the string `"Farewell"`
34
+ content:
35
+ 'text/plain':
36
+ schema:
37
+ type: text
38
+ value: Farewell
39
+ example: Farewell
40
+ 401:
41
+ description: If this is an unauthenticated request (not signed in), `"401 Unauthorized"` is returned
42
+ content:
43
+ 'application/json':
44
+ schema:
45
+ type: object
46
+ properties:
47
+ code:
48
+ type: string
49
+ value: unauthenticated_delete
50
+ message:
51
+ type: string
52
+ value: You are not authorized to perform this operation, your attempt has been logged
53
+ example:
54
+ code: unauthenticated_delete
55
+ message: You are not authorized to perform this operation, your attempt has been logged
56
+ 403:
57
+ description: If a non-admin user tries to update a user's account details, `"403 Forbidden"` is returned
58
+ content:
59
+ 'application/json':
60
+ schema:
61
+ type: object
62
+ properties:
63
+ code:
64
+ type: string
65
+ value: unauthorized_delete
66
+ message:
67
+ type: string
68
+ value: You are not authorized to perform this operation. This attempt has been logged.
69
+ example:
70
+ code: unauthorized_delete
71
+ message: You are not authorized to perform this operation. This attempt has been logged.
72
+ 500:
73
+ description: An unenexpected error occurred on the server
74
+ content:
75
+ 'application/json':
76
+ schema:
77
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,49 @@
1
+ /auth/{dbname}/forgot_password:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Issues a password reset for a user that forgot their password. User must have an email address in the database.
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: user details
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ type: object
20
+ properties:
21
+ email:
22
+ type: string
23
+ description: User's email address. A password reset email will be sent to this address
24
+ required:
25
+ - email
26
+ responses:
27
+ 200:
28
+ description: If a password reset email has been successfully sent, returns the string `"OK"`
29
+ content:
30
+ 'text/plain':
31
+ schema:
32
+ type: 'string'
33
+ value: OK
34
+ description: The string `"OK"`
35
+ 400:
36
+ description: Returns a `"400 Bad Request"` if the server has not been configured properly, or if no or invalid email address was sent with the request
37
+ content:
38
+ 'application/json':
39
+ schema:
40
+ $ref: '#/components/schemas/Error'
41
+ example:
42
+ code: invalid_email
43
+ message: Email address not found, or duplicate entries found
44
+ 500:
45
+ description: An unexpected error occurred
46
+ content:
47
+ 'application/json':
48
+ schema:
49
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,53 @@
1
+ /auth/{dbname}/reset_password:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Completes a password reset request for a user account with a code sent to the email address by the `forgot_password` endpoint
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: verification object
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ type: object
20
+ properties:
21
+ code:
22
+ type: string
23
+ description: Password reset code that was sent to the user's email address
24
+ password:
25
+ type: string
26
+ description: New password to set on the account
27
+ required:
28
+ - code
29
+ - password
30
+ responses:
31
+ 200:
32
+ description: If the password reset is successful, returns the string `"OK"`
33
+ content:
34
+ 'text/plain':
35
+ schema:
36
+ type: 'string'
37
+ value: OK
38
+ description: The string `"OK"`
39
+ 400:
40
+ description: Returns a `"401 Bad Request"` if the code sent with the request is invalid, or the new password doesn't meet the requirements
41
+ content:
42
+ 'application/json':
43
+ schema:
44
+ $ref: '#/components/schemas/Error'
45
+ example:
46
+ code: invalid_code
47
+ message: Invalid token
48
+ 500:
49
+ description: An unexpected error occurred
50
+ content:
51
+ 'application/json':
52
+ schema:
53
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,129 @@
1
+ /auth/{dbname}/signin:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Signs in an existing user
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: sign in details
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ oneOf:
20
+ - type: object
21
+ properties:
22
+ client_id:
23
+ description: ID of the connected websocket
24
+ type: string
25
+ method:
26
+ description: Method of authentication (email)
27
+ type: string
28
+ value: email
29
+ email:
30
+ description: User email address
31
+ type: string
32
+ password:
33
+ description: Password
34
+ type: string
35
+ format: password
36
+ required:
37
+ - method
38
+ - email
39
+ - password
40
+ example:
41
+ method: email
42
+ email: user@example.com
43
+ password: sup3rs3cr3t
44
+ - type: object
45
+ properties:
46
+ client_id:
47
+ description: ID of the connected websocket
48
+ type: string
49
+ method:
50
+ description: Method of authentication (username)
51
+ type: string
52
+ value: username
53
+ username:
54
+ description: Username
55
+ type: string
56
+ password:
57
+ description: Password
58
+ type: string
59
+ format: password
60
+ required:
61
+ - method
62
+ - username
63
+ - password
64
+ example:
65
+ method: username
66
+ username: user
67
+ password: sup3rs3cr3t
68
+ - type: object
69
+ properties:
70
+ client_id:
71
+ type: string
72
+ description: ID of the connected websocket
73
+ method:
74
+ type: string
75
+ value: token
76
+ description: Method of authentication (token)
77
+ token:
78
+ type: string
79
+ description: Previously acquired access token to sign in with
80
+ required:
81
+ - method
82
+ - token
83
+ example:
84
+ method: token
85
+ token: ewufh387f3fyubqwekrjbcqwkuiec7gq3euyfbqwkuyebqjk..
86
+ responses:
87
+ 200:
88
+ description: When signin succeeds, it returns an object with the result
89
+ content:
90
+ 'application/json':
91
+ schema:
92
+ type: object
93
+ properties:
94
+ access_token:
95
+ description: The access token that provides access to API calls that require authentication. This access token should be added to the Authorization header of those requests. The token is allowed to be cached by the client to sign in witht the token method later
96
+ type: string
97
+ example: ewufh387f3fyubqwekrjbcqwkuiec7gq3euyfbqwkuyebqjk..
98
+ user:
99
+ $ref: '#/components/schemas/User'
100
+ 401:
101
+ description: When the sent request details are incorrect, this "401 Unauthorized" is returned
102
+ content:
103
+ 'application/json':
104
+ schema:
105
+ type: object
106
+ properties:
107
+ code:
108
+ type: string
109
+ description: The exact error code
110
+ enum:
111
+ - invalid_token
112
+ - not_found
113
+ - duplicate
114
+ - token_mismatch
115
+ - wrong_password
116
+ example: not_found
117
+ message:
118
+ type: string
119
+ description: Description of the error
120
+ example: Incorrect email
121
+ example:
122
+ code: wrong_password
123
+ message: Incorrect password
124
+ 500:
125
+ description: An unenexpected error occurred on the server
126
+ content:
127
+ 'application/json':
128
+ schema:
129
+ $ref: '#/components/schemas/UnexpectedError'
@@ -0,0 +1,45 @@
1
+ /auth/{dbname}/signout:
2
+ tags:
3
+ - auth
4
+ post:
5
+ description: Signs in an existing user
6
+ parameters:
7
+ - name: dbname
8
+ in: path
9
+ description: name of the database
10
+ required: true
11
+ schema:
12
+ type: string
13
+ example: mydb
14
+ requestBody:
15
+ description: Sign out details
16
+ content:
17
+ 'application/json':
18
+ schema:
19
+ type: object
20
+ properties:
21
+ client_id:
22
+ type: string
23
+ description: ID of the connected websocket
24
+ everywhere:
25
+ type: boolean
26
+ description: Whether the user should sign out on ALL clients
27
+ example:
28
+ client_id: x8WIv7-mJelg7on_ALbx
29
+ everywhere: false
30
+ responses:
31
+ 200:
32
+ description: Returns `"Bye!"` if signout is successful
33
+ content:
34
+ 'text/plain':
35
+ schema:
36
+ type: string
37
+ value: Bye!
38
+ example: Bye!
39
+ 500:
40
+ description: Returns an object describing an unexpected error
41
+ content:
42
+ 'application/json':
43
+ schema:
44
+ $ref: '#/components/schemas/Error'
45
+