29.0.27 • Published 1 year ago

autumndb v29.0.27

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
1 year ago

npm version

Installation

Install by running:

npm install --save autumndb

Usage

AutumnDB relies on Postgres v12+ and Redis v5+. The easiest way to get run these services is to use Docker via docker-compose up.

import * as autumndb from "autumndb";

const start = async () => {
	// Create a unique logging context for the startup process
	const logContext = {
		id: `AUTUMN_DB_CONTEXT`,
	};

	// Instantiate the redis cache and connect to it
	const cache = new autumndb.Cache({
		mock: false,
		namespace: 'autumndb',
		url: 'redis://redis:6379',
		socket: {
			host: 'redis',
			port: 6379,
			tls: false
		},
	});
	await cache.connect();

	// Setup the kernel
	const { kernel } = await autumndb.Kernel.withPostgres(
		logContext,
		cache,
		backendOptions
		{
			host: 'localhost';
		}
	);

	// Create a new user
	const userCard = await kernel.replaceCard(
		logContext,
		kernel.adminSession(),
		{
			slug: 'user-test',
			type: 'user@1.0.0',
			name: 'Test User',
			data: {
				email: 'test@example.com',
				hash: 'PASSWORDLESS',
				roles: ['user-community'],
			},
		},
	);
};

start();

Documentation

Publish Documentation

Visit the website for complete documentation: https://product-os.github.io/autumndb

Features

AutumnDB provides the following features

The contract data model

Every entity in the system is a data structure we call a "contract". Contracts are an implementation of the contracts data model.

Every contract has a type field that specifies type that the contract is an instance of. Contract type definitions are indicated by having a type of type, e.g.

{
	"slug": "message",
	"type": "type",
	...
}

These "type" contracts contain model definitions in the form of a JSON schema. The slug of a type contract is the value used in the type property of instances of the type. As an example, you can look at the type contract for a "user". You can see that under the data key, there is a schema value that defines the shape of a contract of type "message". We follow the JSON schema spec, so if the schema allows, additional fields can be added to a contract that are not defined in the type schema.

JSON schema based querying

JSON schema is used to query the API, with any contracts that match the provided JSON schema being returned in the result set.

JSON patch

Contract updates are made using JSON patch, allowing fine grained updates to made to JSON data.

User system

User contracts model the actors that interact with the system. There are two default users, the admin And the guest. The admin user is typically used for system level operations or operations that require unrestricted access. The guest user represents an unauthorised user interacting with the system. Users authorize function calls using a session, which corresponds to the ID of a "session" contract in the system. The data that a user has access to is defined using "role" contracts. All user contracts define a list of roles that they have.

Role based permissions

Every user in the system must have at least one role, which corresponds to a contract of type "role". Role contracts contain a schema that defines which contracts the user with that role can read and write. When a query is made, the schemas in the user's roles are combined with the user's query using an AND operator. Additionally, roles can specify which fields should be returned by interpreting the use of additionalProperties: false in JSON schemas. If additionalProperties is set to false in a JSON schema, then only the defined properties in the schema will be returned. When combined with role schemas, you can set permissions on a per-field basis. For example, we can express that a user can view their password hash, but not other user's. This behaviour is based on the AJV "removeAdditional" option.

Marker based permissions

The roles system is complemented by another permissions system called "markers". Markers allow individual contracts to be restricted to one or more users. A marker is a string that corresponds to either a user or organisation slug and they appear as an array at the top level of a contract under the key markers.

{
	...
	"markers": [ "user-lucianbuzzo", "org-balena" ]
	...
}

To view a contract, a user must have access to all the markers on that contract. A user has access to their marker (which is the slug of their user contract) and the markers for each organisation they are a member of. Markers can also be in the form of a compound marker, which is 2 or more markers concatenated with a + symbol. A user has access to a contract with a compound marker if they have access to at least one of the markers that make up the compound marker. If a contract has no markers on it, then the contract is unrestricted by the markers system.

For example, if my user slug is user-lucianbuzzo and I am a member of the org-balena org, then I would be able to view contracts with the markers:

  • [] (i.e. no markers defined)
  • [ "org-balena", "user-lucianbuzzo" ]
  • [ "user-lucianbuzzo" ]
  • [ "org-balena+user-lucianbuzzo" ]
  • [ "foobar+user-lucianbuzzo" ]
  • [ "org-balena+user-foobar" ]

However, I wouldn't be able to view contracts with the markers

  • [ "user-foobar" ]
  • [ "user-foobar", "user-lucianbuzzo" ]
  • [ "org-balena", "user-foobar" ]
  • [ "org-balena", "user-foobar+user-bazbuzz" ]

Organisations

Users can belong to organisations.

Streaming

A query can be streamed, creating an event emitter that will emit an event on any insert or update to a contract.

Soft delete

When a contract is deleted, it is not removed from the database but has it's "active" field set to false. It is recommended that users should not be able to view inactive contracts.

Rich logging

When a code path is run, a context object is passed through the call stack. Each context object has a unique ID that is used in log generation, allowing logs to be easily aggregated to observe codepaths.

Built-in metric gathering

Measurable are gathered and observed using prometheus/grafana.

Data relationships

Contracts can be linked together by creating a contract of type "link" that references both contracts and describes their relationship. Relationships can be traversed when querying data using the $$links syntax.

Caching

Requests for individual contracts by id or slug are cached, reducing DB load and improving query speed.

Testing

Unit tests can be easily run with the command npm test.

The integration tests require Postgres and Redis instances. The simplest way to run the tests locally is with docker-compose.

$ npm run test:compose

You can also run tests locally against Postgres and Redis instances running in docker-compose:

$ npm run compose
$ REDIS_HOST=localhost POSTGRES_HOST=localhost npx jest test/integration/permission-filter.spec.ts

You can also access these Postgres and Redis instances:

$ PGPASSWORD=docker psql -hlocalhost -Udocker
$ redis-cli -h localhost
29.0.9

1 year ago

29.0.5

1 year ago

29.0.6

1 year ago

29.0.7

1 year ago

29.0.8

1 year ago

29.0.1

1 year ago

29.0.2

1 year ago

29.0.3

1 year ago

29.0.4

1 year ago

29.0.0

1 year ago

29.0.22

1 year ago

29.0.21

1 year ago

29.0.24

1 year ago

29.0.23

1 year ago

29.0.20

1 year ago

29.0.26

1 year ago

29.0.25

1 year ago

29.0.27

1 year ago

29.0.11

1 year ago

29.0.10

1 year ago

29.0.13

1 year ago

29.0.12

1 year ago

29.0.19

1 year ago

29.0.18

1 year ago

29.0.15

1 year ago

29.0.14

1 year ago

29.0.17

1 year ago

29.0.16

1 year ago

28.1.0

2 years ago

28.1.1

2 years ago

27.0.0

2 years ago

28.0.0

2 years ago

28.0.1

2 years ago

28.0.2

2 years ago

28.0.3

2 years ago

22.10.1

2 years ago

22.10.0

2 years ago

25.0.0

2 years ago

26.0.5

2 years ago

26.0.4

2 years ago

26.0.3

2 years ago

26.0.2

2 years ago

26.0.1

2 years ago

26.0.0

2 years ago

22.9.0

2 years ago

23.0.4

2 years ago

23.0.3

2 years ago

23.0.0

2 years ago

23.0.2

2 years ago

23.0.1

2 years ago

24.0.4

2 years ago

24.0.3

2 years ago

24.0.2

2 years ago

24.0.1

2 years ago

24.0.0

2 years ago

22.8.1

2 years ago

22.8.0

2 years ago

22.3.0

2 years ago

22.5.3

2 years ago

22.5.2

2 years ago

22.5.1

2 years ago

22.7.0

2 years ago

22.2.189

2 years ago

22.4.0

2 years ago

22.2.181

2 years ago

22.2.182

2 years ago

22.2.183

2 years ago

22.2.184

2 years ago

22.2.185

2 years ago

22.2.186

2 years ago

22.2.187

2 years ago

22.2.188

2 years ago

22.2.156

2 years ago

22.2.157

2 years ago

22.2.158

2 years ago

22.2.159

2 years ago

22.2.150

2 years ago

22.2.151

2 years ago

22.2.152

2 years ago

22.2.153

2 years ago

22.2.154

2 years ago

22.2.145

2 years ago

22.2.146

2 years ago

22.2.148

2 years ago

22.2.149

2 years ago

22.2.140

2 years ago

22.2.141

2 years ago

22.2.142

2 years ago

22.2.143

2 years ago

22.2.144

2 years ago

22.2.180

2 years ago

22.2.178

2 years ago

22.2.179

2 years ago

22.2.170

2 years ago

22.2.171

2 years ago

22.2.172

2 years ago

22.2.173

2 years ago

22.2.174

2 years ago

22.2.175

2 years ago

22.2.176

2 years ago

22.2.177

2 years ago

22.2.167

2 years ago

22.2.169

2 years ago

22.2.160

2 years ago

22.2.161

2 years ago

22.2.162

2 years ago

22.2.163

2 years ago

22.2.164

2 years ago

22.2.165

2 years ago

22.2.166

2 years ago

22.2.113

2 years ago

22.2.114

2 years ago

22.2.115

2 years ago

22.2.116

2 years ago

22.2.117

2 years ago

22.2.118

2 years ago

22.2.119

2 years ago

22.2.134

2 years ago

22.2.135

2 years ago

22.2.136

2 years ago

22.2.137

2 years ago

22.2.138

2 years ago

22.2.139

2 years ago

22.2.130

2 years ago

22.2.131

2 years ago

22.2.132

2 years ago

22.2.133

2 years ago

22.2.123

2 years ago

22.2.124

2 years ago

22.2.125

2 years ago

22.2.126

2 years ago

22.2.127

2 years ago

22.2.128

2 years ago

22.2.129

2 years ago

22.2.120

2 years ago

22.2.121

2 years ago

22.2.122

2 years ago

22.2.73

2 years ago

22.2.74

2 years ago

22.2.71

2 years ago

22.2.72

2 years ago

22.2.70

2 years ago

22.2.79

2 years ago

22.2.77

2 years ago

22.2.78

2 years ago

22.2.75

2 years ago

22.2.76

2 years ago

22.2.84

2 years ago

22.2.85

2 years ago

22.2.82

2 years ago

22.2.83

2 years ago

22.2.80

2 years ago

22.2.81

2 years ago

22.2.88

2 years ago

22.2.89

2 years ago

22.2.86

2 years ago

22.2.87

2 years ago

22.2.95

2 years ago

22.2.96

2 years ago

22.2.93

2 years ago

22.2.94

2 years ago

22.2.91

2 years ago

22.2.92

2 years ago

22.2.90

2 years ago

22.2.99

2 years ago

22.2.97

2 years ago

22.2.98

2 years ago

22.2.19

2 years ago

22.2.17

2 years ago

22.2.18

2 years ago

22.2.15

2 years ago

22.2.16

2 years ago

22.2.13

2 years ago

22.2.14

2 years ago

22.2.11

2 years ago

22.2.12

2 years ago

22.2.10

2 years ago

22.2.28

2 years ago

22.2.29

2 years ago

22.2.26

2 years ago

22.2.27

2 years ago

22.2.24

2 years ago

22.2.25

2 years ago

22.2.22

2 years ago

22.2.23

2 years ago

22.2.20

2 years ago

22.2.21

2 years ago

22.2.39

2 years ago

22.2.30

2 years ago

22.2.37

2 years ago

22.2.38

2 years ago

22.2.35

2 years ago

22.2.36

2 years ago

22.2.33

2 years ago

22.2.34

2 years ago

22.2.31

2 years ago

22.2.32

2 years ago

22.2.40

2 years ago

22.2.41

2 years ago

22.2.48

2 years ago

22.2.49

2 years ago

22.2.46

2 years ago

22.2.47

2 years ago

22.2.44

2 years ago

22.2.45

2 years ago

22.2.42

2 years ago

22.2.43

2 years ago

22.2.51

2 years ago

22.2.52

2 years ago

22.2.50

2 years ago

22.2.59

2 years ago

22.2.57

2 years ago

22.2.58

2 years ago

22.2.55

2 years ago

22.2.56

2 years ago

22.2.53

2 years ago

22.2.54

2 years ago

22.2.62

2 years ago

22.2.63

2 years ago

22.2.60

2 years ago

22.2.61

2 years ago

22.2.68

2 years ago

22.2.69

2 years ago

22.2.66

2 years ago

22.2.67

2 years ago

22.2.64

2 years ago

22.2.65

2 years ago

22.2.112

2 years ago

22.2.110

2 years ago

22.2.111

2 years ago

22.2.109

2 years ago

22.2.101

2 years ago

22.2.102

2 years ago

22.2.103

2 years ago

22.2.104

2 years ago

22.2.105

2 years ago

22.2.106

2 years ago

22.2.107

2 years ago

22.2.108

2 years ago

22.2.100

2 years ago

22.2.1

2 years ago

22.2.0

2 years ago

22.2.9

2 years ago

22.2.8

2 years ago

22.2.7

2 years ago

22.2.6

2 years ago

22.2.5

2 years ago

22.2.4

2 years ago

22.2.3

2 years ago

22.2.2

2 years ago

20.1.11

3 years ago

20.1.12

3 years ago

20.1.13

3 years ago

20.1.14

3 years ago

20.1.15

3 years ago

20.1.16

3 years ago

20.1.17

3 years ago

20.1.18

3 years ago

20.1.19

3 years ago

20.1.20

3 years ago

20.1.21

3 years ago

20.1.22

2 years ago

20.1.23

2 years ago

20.1.24

2 years ago

20.1.25

2 years ago

21.3.11

2 years ago

21.3.12

2 years ago

21.3.10

2 years ago

21.3.15

2 years ago

21.3.13

2 years ago

21.3.14

2 years ago

22.1.18

2 years ago

22.1.19

2 years ago

22.1.16

2 years ago

22.1.17

2 years ago

22.1.14

2 years ago

22.1.15

2 years ago

22.1.12

2 years ago

22.1.13

2 years ago

22.1.10

2 years ago

22.1.11

2 years ago

21.0.0

2 years ago

20.2.3

2 years ago

20.2.2

2 years ago

20.2.1

2 years ago

20.2.0

2 years ago

20.2.4

2 years ago

21.1.1

2 years ago

21.1.0

2 years ago

21.1.3

2 years ago

21.1.2

2 years ago

21.1.5

2 years ago

21.1.4

2 years ago

20.3.2

2 years ago

20.3.1

2 years ago

20.3.0

2 years ago

20.3.6

2 years ago

20.3.5

2 years ago

20.3.4

2 years ago

20.3.3

2 years ago

20.3.7

2 years ago

22.0.3

2 years ago

22.0.2

2 years ago

22.0.1

2 years ago

22.0.0

2 years ago

22.0.8

2 years ago

22.0.7

2 years ago

22.0.6

2 years ago

22.0.5

2 years ago

22.0.4

2 years ago

21.2.0

2 years ago

21.2.1

2 years ago

22.1.2

2 years ago

22.1.1

2 years ago

22.1.0

2 years ago

22.1.9

2 years ago

22.1.8

2 years ago

22.1.7

2 years ago

22.1.6

2 years ago

22.1.5

2 years ago

22.1.4

2 years ago

22.1.3

2 years ago

21.3.1

2 years ago

21.3.0

2 years ago

21.3.7

2 years ago

21.3.6

2 years ago

21.3.9

2 years ago

21.3.8

2 years ago

21.3.3

2 years ago

21.3.2

2 years ago

21.3.5

2 years ago

21.3.4

2 years ago

22.1.27

2 years ago

22.1.28

2 years ago

22.1.25

2 years ago

22.1.26

2 years ago

22.1.23

2 years ago

22.1.24

2 years ago

22.1.21

2 years ago

22.1.22

2 years ago

22.1.20

2 years ago

20.1.10

3 years ago

19.1.39

3 years ago

19.1.38

3 years ago

19.3.0

3 years ago

19.1.40

3 years ago

19.3.1

3 years ago

19.1.41

3 years ago

19.2.0

3 years ago

20.0.1

3 years ago

20.0.0

3 years ago

20.0.5

3 years ago

20.0.4

3 years ago

20.0.3

3 years ago

20.0.2

3 years ago

20.0.9

3 years ago

20.0.8

3 years ago

20.0.7

3 years ago

20.0.6

3 years ago

20.1.0

3 years ago

20.1.4

3 years ago

20.1.3

3 years ago

20.1.2

3 years ago

20.1.1

3 years ago

20.1.8

3 years ago

20.1.7

3 years ago

20.1.6

3 years ago

20.1.5

3 years ago

20.1.9

3 years ago

19.1.29

3 years ago

19.1.28

3 years ago

19.1.27

3 years ago

19.1.22

3 years ago

19.1.21

3 years ago

19.1.20

3 years ago

19.1.26

3 years ago

19.1.25

3 years ago

19.1.24

3 years ago

19.1.23

3 years ago

19.1.33

3 years ago

19.1.32

3 years ago

19.1.31

3 years ago

19.1.30

3 years ago

19.1.37

3 years ago

19.1.36

3 years ago

19.1.35

3 years ago

19.1.34

3 years ago

19.1.19

3 years ago

19.1.18

3 years ago

19.1.17

3 years ago

19.1.16

3 years ago

19.1.15

3 years ago

19.1.14

3 years ago

19.1.13

3 years ago

19.1.12

3 years ago

19.1.11

3 years ago

19.1.10

3 years ago

19.1.9

3 years ago

19.1.8

3 years ago

19.1.7

3 years ago

19.1.6

3 years ago

19.1.5

3 years ago

19.1.4

3 years ago

19.1.3

3 years ago

19.1.2

3 years ago

19.1.1

3 years ago

19.1.0

3 years ago

19.0.4

3 years ago

19.0.3

3 years ago

19.0.2

3 years ago

19.0.1

3 years ago

19.0.0

3 years ago

18.0.0

3 years ago

17.0.6

3 years ago

17.0.5

3 years ago

17.0.4

3 years ago

17.0.3

3 years ago

17.0.2

3 years ago

17.0.1

3 years ago

17.0.0

3 years ago