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

• Serverless Fauna
  • Installation
  • Commands
  • Configuration
    • Collection configuration
    • Function configuration
    • Index configuration
      • Index source
      • Index terms
      • Index values
      • Index binding
    • Role configuration
      • Role schema privileges
      • Role membership
  • Deletion policy

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