serverless-fauna
v0.1.0
Published
A plugin to define resources in your Fauna database directly within your Serverless Framework applications.
Downloads
4
Maintainers
Readme
This repository contains unofficial patterns, sample code, or tools to help developers build more effectively with Fauna. All Fauna Labs repositories are provided “as-is” and without support. By using this repository or its contents, you agree that this repository may never be officially supported and moved to the Fauna organization.
Serverless Fauna
A serverless plugin to easily describe Fauna infrastructure as a code. Plugins helps to keep Fauna up to serverless configuration and will create/update resources such as collections/indexes
Installation
$ npm install serverless-fauna --save-dev
or using yarn
$ yarn add serverless-fauna
Commands
The plugin listens hooks from default serverless command and run his own logic
| command | description |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| sls deploy | sync Fauna resources specified a config. All resources created by the plugin has boolean property created_by_serverless_plugin
set to true
|
| sls remove | sync Fauna resources created by plugin read more about deleting policy |
If you would like to run only the Fauna plugin logic, you can just add fauna
before the command. (ex: sls fauna deploy
)
Configuration
plugins:
- serverless-fauna
fauna:
client:
secret: ${env:FAUNA_ROOT_KEY}
# domain: db.fauna.com
# port: 433
# scheme: https
collections:
Movies:
name: Movies
data:
some_data_key: some_data_value
functions:
double:
name: double
body: ${file('./double.fql')}
indexes:
movies_by_type:
name: movies_by_type
source: ${self:fauna.collections.Movies.name}
terms:
fields:
- data.type
movies_by_category:
name: movies_by_category
source: ${self:fauna.collections.Movies.name}
data:
some_data_key: some_data_value
terms:
fields:
- data.category
sort_by_year:
name: sort_by_year
source: ${self:fauna.collections.Movies.name}
values:
fields:
- data.type
- ref
Collection configuration
Can accept any param that accept CreateCollection
query.
Read more about params here
collections:
Movies:
name: Movies
history_days: 30
ttl_days: 10
data:
some_data_key: some_data_value
Function configuration
Can accept any param that accept CreateFunction
query.
Read more about params here
functions:
double:
name: double
body: ${file('./double.fql')}
role: admin
data:
desc: double number
Index configuration
Can accept any param that accept CreateIndex query. Read more about params here
terms
, values
and source
can be set only if index doesn't exists. If you change those configuration for existing index, plugin would throw an error when tried update it
search_by_category_and_sort_by_year:
name: search_by_category_and_sort_by_year
source:
collection: ${self:fauna.collections.Movies.name}
fields:
is_current_year: ${file(./IsCurrentYear.fql)}
terms:
fields:
-data.category
values:
fields:
- path: data.type
reverse: true
- ref
bindings:
- is_current_year
Index source
Index source could be a string and interpreted as collection reference
source: Movie
Or a source object. Read more about source object
source:
collection: Movie
Or an array of object
source:
- collection: Movies
- collection: Cartoons
- collection: Series
Index terms
terms:
fields:
- data.search
bindings:
- binding
Index values
Index values looks pretty the same as terms, but has additional reverse
field which determinate sort order
values:
fields:
- path: data.field
reverse: true
bindings:
- binding
Index binding
Index allow you to compute fields for a source while the document is being indexed. Read more about index bindings You can specify multiline fql
source:
collection: Movies
fields:
is_current_year: >
Equals([
Year(Now()),
ToInteger(Select(['data', 'release_year'], Var('doc')))
])
Or create file with .fql
extension. We have Fauna VSCode plugin to handle .fql
files
source:
collection: Movies
fields:
is_current_year: ${file(./IsCurrentYear.fql)}
Role configuration
Can accept any param that accept CreateRole query. Read more about params here
roles:
movies_reader:
name: movies_reader
privileges:
- collection: ${self:fauna.collections.movies.name}
actions:
read: true
- index: ${self:fauna.indexes.movies_by_type.name}
actions:
read: true
- function: ${self:fauna.functions.double.name}
actions:
call: true
Role schema privileges
Read more about privilege configuration object
For schema privileges just specify field key without value
roles:
read_collections_and indexes:
name: read_collections
privileges:
- collections:
actions:
read: true
- indexes:
actions:
read: true
You can also pass action predicate
editors:
name: editors
membership:
- ${self:fauna.collections.scriptwriters.name}
- ${self:fauna.collections.directors.name}
privileges:
- collection: ${self:fauna.collections.movies.name}
actions:
read: true
write: ${file(./CanModifyMovie.fql)}
Role membership
A membership configuration object dynamically defines which authenticated resources are members of a given role.
roles:
actor:
name: actor
membership: actor
Or as an array
roles:
actor:
name: participant
membership:
- actor
- directors
You can also pass membership object
roles:
only_active:
name: only_active
membership:
resource: ${self:fauna.collections.users.name}
predicate: ${file(./IsActiveUser.fql)}
Or an array of membership objects
roles:
only_active:
name: only_granted
membership:
- resource: ${self:fauna.collections.users.name}
predicate: ${file(./IsGranted.fql)}
- resource: ${self:fauna.collections.managers.name}
predicate: ${file(./IsGranted.fql)}
Deletion policy
Plugin keeps sync between serverless configuration and the current Fauna state. Therefore, the plugin will remove all resources that currently exist at the Fauna but not declared at configuration would be removed. However, there are some resources that you absolutely do not want get deleted.
You can set deletion_policy
to retain
. (default destroy
) to the top level fauna
configuration
In example below, Fauna resources would not be deleted
fauna:
deleting_policy: retain
In spite of property deleting_policy
specified at the top level, resource level property has a higher priority. Therefore, with the following configuration collection logs
would be removed and the rest of resources will be saved
fauna:
deleting_policy: retain
collections:
Movies:
name: Movies
logs:
name: logs
deleting_policy: destroy
Copyright Fauna, Inc. or its affiliates. All rights reserved. SPDX-License-Identifier: MIT-0