graphik

README

Graphik

https://graphikdb.github.io/graphik/

git clone git@github.com:graphikDB/graphik.git

docker pull graphikdb/graphik:v0.2.1

Graphik is an identity-aware, permissioned, persistant document & graph database written in Go

• Helpful Links
• Features
• Key Dependencies
• Flags
• gRPC Client SDKs
• Implemenation Details
  • Primitives
  • Login/Authorization/Authorizers
    • Authorizers Examples
  • Secondary Indexes
    • Secondary Index Examples
  • Type Validators
    • Type Validator Examples
  • Identity Graph
  • Additional Details
• Sample GraphQL Queries
  • Node Traversal
• Deployment
  • Docker-Compose
  • Kubernetes
  • Virtual Machine

Helpful Links

• GraphQL Documentation Site
• Protobuf/gRPC API Spec
• Graphql API Spec
• Common Expression Language Code Lab
• CEL Standard Functions/Definitions
• OpenID Connect
• Directed Graph Wiki

Features

• 100% Go
• Native gRPC Support
• GraphQL Support
• Native Document & Graph Database
• Index-free Adjacency
• Native OAuth/OIDC Support & Single Sign On
• Embedded SSO protected GraphQl Playground
• Persistant(bbolt LMDB)
• Identity-Aware PubSub with Channels & Message Filtering(gRPC & graphQL)
• Common Expression Language Query Filtering
• Common Expression Language Request Authorization
• Common Expression Language Type Validators
• Loosely-Typed(mongo-esque)
• Prometheus Metrics
• Pprof Metrics
• Safe to Deploy Publicly(with authorizers)
• Read-Optimized
• Full Text Search(CEL)
• Regular Expressions(CEL)
• Client to Server streaming(gRPC only)

Key Dependencies

• google.golang.org/grpc
• github.com/autom8ter/machine
• github.com/google/cel-go/cel
• go.etcd.io/bbolt
• go.uber.org/zap
• golang.org/x/oauth2
• github.com/99designs/gqlgen

Flags

      --allow-headers strings             cors allow headers (env: GRAPHIK_ALLOW_HEADERS) (default [*])
      --allow-methods strings             cors allow methods (env: GRAPHIK_ALLOW_METHODS) (default [HEAD,GET,POST,PUT,PATCH,DELETE])
      --allow-origins strings             cors allow origins (env: GRAPHIK_ALLOW_ORIGINS) (default [*])
      --metrics                           enable prometheus & pprof metrics (emv: GRAPHIK_METRICS = true) (default true)
      --open-id string                    open id connect discovery uri ex: https://accounts.google.com/.well-known/openid-configuration (env: GRAPHIK_OPEN_ID)
      --playground-client-id string       playground oauth client id (env: GRAPHIK_PLAYGROUND_CLIENT_ID)
      --playground-client-secret string   playground oauth client secret (env: GRAPHIK_PLAYGROUND_CLIENT_SECRET
      --playground-redirect string        playground oauth redirect (env: GRAPHIK_PLAYGROUND_REDIRECT) (default "http://localhost:7820/playground/callback")
      --root-users strings                a list of email addresses that bypass registered authorizers(env: GRAPHIK_ROOT_USERS)
      --storage string                    persistant storage path (env: GRAPHIK_STORAGE_PATH) (default "/tmp/graphik")
      --tls-cert string                   path to tls certificate (env: GRAPHIK_TLS_CERT)
      --tls-key string                    path to tls key (env: GRAPHIK_TLS_KEY)

gRPC Client SDKs

• Go
• Python
• PHP
• Javascript
• Java
• C#
• Ruby

Implemenation Details

Please see GraphQL Documentation Site for additional details

Primitives

• Ref == direct pointer to an doc or connection.

message Ref {
  // gtype is the type of the doc/connection ex: pet
  string gtype =1 [(validator.field) = {regex : "^.{1,225}$"}];
  // gid is the unique id of the doc/connection within the context of it's type
  string gid =2 [(validator.field) = {regex : "^.{1,225}$"}];
}

• Doc == JSON document in document storage terms AND vertex/node in graph theory

message Doc {
    // ref is the ref to the doc
    Ref ref =1 [(validator.field) = {msg_exists : true}];
    // k/v pairs
    google.protobuf.Struct attributes =2;
}

• Connection == graph edge/relationship in graph theory. Connections relate Docs to one another.

message Connection {
  // ref is the ref to the connection
  Ref ref =1 [(validator.field) = {msg_exists : true}];
  // attributes are k/v pairs
  google.protobuf.Struct attributes =2;
  // directed is false if the connection is bi-directional
  bool directed =3;
  // from is the doc ref that is the source of the connection
  Ref from =4 [(validator.field) = {msg_exists : true}];
  // to is the doc ref that is the destination of the connection
  Ref to =5 [(validator.field) = {msg_exists : true}];
}

Login/Authorization/Authorizers

• an access token Authorization: Bearer ${token} from the configured open-id connect identity provider is required for all database functionality
• the access token is used to fetch the users info from the oidc userinfo endpoint fetched from the oidc metadata url
• if a user is not present in the database, one will be automatically created under the gtype: user with their email address as their gid
• once the user is fetched, it is evaluated(along with the request & request method) against any registered authorizers(CEL expression) in the database.
  • if an authorizer evaluates false, the request will be denied
  • authorizers may be used to restrict access to functionality by domain, role, email, etc
  • registered root users(see flags) bypass these authorizers
• authorizers are completely optional but highly recommended

Authorizers Examples

Coming Soon

Secondary Indexes

• secondary indexes are CEL expressions evaluated against a particular type of Doc or Connection
• indexes may be used to speed up queries that iterate over a large number of elements
• secondary indexes are completely optional but recommended

Secondary Index Examples

Coming Soon

Type Validators

• type validators are CEL expressions evaluated against a particular type of Doc or Connection to enforce custom constraints
• type validators are completely optional

Type Validator Examples

Coming Soon

Identity Graph

• any time a document is created, a connection of type created from the origin user to the new document is also created
• any time a document is created, a connection of type created_by from the new document to the origin user is also created
• any time a document is edited, a connection of type edited from the origin user to the new document is also created(if none exists)
• any time a document is edited, a connection of type edited_by from the new document to the origin user is also created(if none exists)
• every document a user has ever interacted with may be queried via the Traverse method with the user as the root document of the traversal

Additional Details

• any time a Doc is deleted, so are all of its connections

Sample GraphQL Queries

Node Traversal

# Write your query or mutation here
query {
  traverse(input: {
    root: {
      gid: "coleman.word@graphikdb.io"
      gtype: "user"
    }
    algorithm: BFS
    limit: 6
		max_depth: 1
		max_hops: 10
  }){
    traversals {
      doc {
        ref {
          gid
          gtype
        }
      }
      traversal_path {
        gid
        gtype
      }
			depth
			hops
    }
  }
}

Deployment

Docker-Compose

add this docker-compose.yml to ${pwd}:

version: '3.7'
services:
  graphik:
    image: graphikdb/graphik:v0.2.1
    env_file:
      - .env
    ports:
      - "7820:7820"
      - "7821:7821"
    volumes:
      - default:/tmp/graphik
    networks:
      default:
        aliases:
          - graphikdb
networks:
  default:

volumes:
  default:

add a .env file to ${pwd}

GRAPHIK_PLAYGROUND_CLIENT_ID=${client_id}
GRAPHIK_PLAYGROUND_CLIENT_SECRET=${client_secret}
GRAPHIK_PLAYGROUND_REDIRECT=http://localhost:7820/playground/callback
GRAPHIK_OPEN_ID=${open_id_connect_metadata_url}
#GRAPHIK_ALLOW_HEADERS=${cors_headers}
#GRAPHIK_ALLOW_METHOD=${cors_methos}
#GRAPHIK_ALLOW_ORIGINS=${cors_origins}
#GRAPHIK_ROOT_USERS=${root_users}
#GRAPHIK_TLS_CERT=${tls_cert_path}
#GRAPHIK_TLS_KEY=${tls_key_path}

then run:

docker-compose -f docker-compose.yml pull
docker-compose -f docker-compose.yml up -d

to shutdown:

docker-compose -f docker-compose.yml down --remove-orphans

Kubernetes

Coming Soon

Virtual Machine

Coming Soon