serverless-fauna

    0.1.0 • Public • Published

    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

    Install

    npm i serverless-fauna

    DownloadsWeekly Downloads

    1

    Version

    0.1.0

    License

    MIT-0

    Unpacked Size

    63.3 kB

    Total Files

    25

    Last publish

    Collaborators

    • rts-rob