polyn 0.1.0

data/lib/cloud-event-schema.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "CloudEvents Specification JSON Schema, extended for Polyn",
+  "type": "object",
+  "properties": {
+    "id": {
+      "description": "Identifies the event.",
+      "$ref": "#/definitions/iddef",
+      "examples": [
+        "A234-1234-1234"
+      ]
+    },
+    "source": {
+      "description": "Identifies the context in which an event happened.",
+      "$ref": "#/definitions/sourcedef",
+      "examples" : [
+        "https://github.com/cloudevents",
+        "mailto:cncf-wg-serverless@lists.cncf.io",
+        "urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66",
+        "cloudevents/spec/pull/123",
+        "/sensors/tn-1234567/alerts",
+        "1-555-123-4567"
+      ]
+    },
+    "specversion": {
+      "description": "The version of the CloudEvents specification which the event uses.",
+      "$ref": "#/definitions/specversiondef",
+      "examples": [
+        "1.0"
+      ]
+    },
+    "type": {
+      "description": "Describes the type of event related to the originating occurrence.",
+      "$ref": "#/definitions/typedef",
+      "examples" : [
+        "com.github.pull_request.opened",
+        "com.example.object.deleted.v2"
+      ]
+    },
+    "datacontenttype": {
+      "description": "Content type of the data value. Must adhere to RFC 2046 format.",
+      "$ref": "#/definitions/datacontenttypedef",
+      "examples": [
+        "text/xml",
+        "application/json",
+        "image/png",
+        "multipart/form-data"
+      ]
+    },
+    "dataschema": {
+      "description": "Identifies the schema that data adheres to.",
+      "$ref": "#/definitions/dataschemadef"
+    },
+    "subject": {
+      "description": "Describes the subject of the event in the context of the event producer (identified by source).",
+      "$ref": "#/definitions/subjectdef",
+      "examples": [
+        "mynewfile.jpg"
+      ]
+    },
+    "time": {
+      "description": "Timestamp of when the occurrence happened. Must adhere to RFC 3339.",
+      "$ref": "#/definitions/timedef",
+      "examples": [
+        "2018-04-05T17:31:00Z"
+      ]
+    },
+    "data": {
+      "description": "The event payload.",
+      "$ref": "#/definitions/datadef",
+      "examples": [
+        "<much wow=\"xml\"/>"
+      ]
+    },
+    "data_base64": {
+      "description": "Base64 encoded event payload. Must adhere to RFC4648.",
+      "$ref": "#/definitions/data_base64def",
+      "examples": [
+        "Zm9vYg=="
+      ]
+    },
+    "polyndata": {
+      "$ref": "#/definitions/polyndatadef",
+      "description": "Information about the client that produced the event and additional metadata",
+      "examples": [
+        {
+          "clientlang": "elixir",
+          "clientlangversion": "1.13.2",
+          "clientversion": "0.1.0"
+        }
+      ]
+    },
+    "polyntrace": {
+      "$ref": "#/definitions/polyntracedef",
+      "description": "Previous events that led to this one",
+      "examples": [
+        [
+          {
+            "type": "<topic>",
+            "time": "2018-04-05T17:31:00Z",
+            "id": "<uuid>"
+          }
+        ]
+      ]
+    }
+  },
+  "required": ["id", "source", "specversion", "type"],
+  "definitions": {
+    "iddef": {
+      "type": "string",
+      "minLength": 1
+    },
+    "sourcedef": {
+      "type": "string",
+      "format": "uri-reference",
+      "minLength": 1
+    },
+    "specversiondef": {
+      "type": "string",
+      "minLength": 1
+    },
+    "typedef": {
+      "type": "string",
+      "minLength": 1
+    },
+    "datacontenttypedef": {
+      "type": ["string", "null"],
+      "minLength": 1
+    },
+    "dataschemadef": {
+      "type": ["string", "null"],
+      "format": "uri",
+      "minLength": 1
+    },
+    "subjectdef": {
+      "type": ["string", "null"],
+      "minLength": 1
+    },
+    "timedef": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "minLength": 1
+    },
+    "datadef": {
+      "type": ["object", "string", "number", "array", "boolean", "null"]
+    },
+    "data_base64def": {
+      "type": ["string", "null"],
+      "contentEncoding": "base64"
+    },
+    "polyndatadef": {
+      "type": "object",
+      "properties": {
+        "clientlang": {
+          "type": "string"
+        },
+        "clientlangversion": {
+          "type": "string"
+        },
+        "clientversion": {
+          "type": "string"
+        }
+      },
+      "required": ["clientlang", "clientlangversion", "clientversion"]
+    },
+    "polyntracedef": {
+      "type" : "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "id"  : {
+            "type": "string",
+            "format": "uuid"
+          }
+        },
+        "required": ["type", "time", "id"]
+      }
+    }
+  }
+}

data/lib/polyn/cloud_event.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Polyn
+  ##
+  # Access cloud event information
+  class CloudEvent
+    def self.to_h
+      path = File.expand_path(File.join(File.dirname(__FILE__), "../cloud-event-schema.json"))
+      file = File.open(path)
+      JSON.parse(file.read)
+    end
+  end
+end

data/lib/polyn/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Polyn
+  ##
+  # Configuration data for Polyn
+  class Configuration
+    def initialize
+      @domain      = nil
+      @source_root = nil
+    end
+
+    def domain
+      @domain ||= Polyn::Naming.validate_domain_name!(@domain)
+    end
+
+    def domain=(name)
+      Polyn::Naming.validate_domain_name!(name)
+      @domain = name
+    end
+
+    def source_root
+      @source_root ||= Polyn::Naming.validate_source_root!(@source_root)
+    end
+
+    def source_root=(name)
+      Polyn::Naming.validate_source_root!(name)
+      @source_root = name
+    end
+  end
+end

data/lib/polyn/errors/configuration_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Polyn
+  module Errors
+    ##
+    # Raised when there is an error with Polyn configuration
+    class ConfigurationError < Error
+    end
+  end
+end

data/lib/polyn/errors/error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Polyn
+  module Errors
+    ##
+    # Polyn base error class.
+    class Error < StandardError
+      def initialize(message = nil, code: 500)
+        super(message)
+      end
+    end
+  end
+end

data/lib/polyn/errors/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "polyn/errors/error"
+require "polyn/errors/configuration_error"
+require "polyn/errors/schema_error"
+require "polyn/errors/validation_error"

data/lib/polyn/errors/schema_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Polyn
+  module Errors
+    ##
+    # Raised when there are problems with the schema aside from validation
+    class SchemaError < Error
+    end
+  end
+end

data/lib/polyn/errors/validation_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Polyn
+  module Errors
+    ##
+    # Raised when a part of the schema is invalid
+    class ValidationError < Error
+    end
+  end
+end

data/lib/polyn/event.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Copyright 2021-2022 Spiff, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this
+# software and associated documentation files (the "Software"), to deal in the Software
+# without restriction, including without limitation the rights to use, copy, modify, merge,
+# publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+# persons to whom the Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all copies or
+# substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+# NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module Polyn
+  ##
+  # Represents an event. Events follow the [Cloudevents](https://github.com/cloudevents)
+  # specification.
+  class Event
+    CLOUD_EVENT_VERSION = "1.0"
+
+    class UnsupportedVersionError < Errors::Error; end
+
+    ##
+    # @return [String] the cloud event version
+    attr_reader :specversion
+
+    ##
+    # @return [String] event id
+    attr_reader :id
+
+    ##
+    # @return [String] event type
+    attr_reader :type
+
+    ##
+    # @return [String] event source
+    attr_reader :source
+
+    ##
+    # @return [String] time of event creation
+    attr_reader :time
+
+    ##
+    # @return [String] the data content type
+    attr_accessor :datacontenttype
+
+    ##
+    # @return [String] the data
+    attr_reader :data
+
+    ##
+    # @return [Array] Previous events that led to this one
+    attr_reader :polyntrace
+
+    ##
+    # @return [Hash] Represents the information about the client that published the event
+    # as well as additional metadata
+    attr_reader :polyndata
+
+    def initialize(hash)
+      @specversion = hash.key?(:specversion) ? hash[:specversion] : "1.0"
+
+      unless Gem::Dependency.new("", "~> #{CLOUD_EVENT_VERSION}").match?("", @specversion)
+        raise UnsupportedVersionError, "Unsupported version: '#{hash[:specversion]}'"
+      end
+
+      @id              = hash.fetch(:id, SecureRandom.uuid)
+      @type            = self.class.full_type(hash.fetch(:type))
+      @source          = self.class.full_source(hash[:source])
+      @time            = hash.fetch(:time, Time.now.utc.iso8601)
+      @data            = hash.fetch(:data)
+      @datacontenttype = hash.fetch(:datacontenttype, "application/json")
+      @polyntrace      = self.class.build_polyntrace(hash[:triggered_by])
+      @polyndata       = {
+        clientlang:        "ruby",
+        clientlangversion: RUBY_VERSION,
+        clientversion:     Polyn::VERSION,
+      }
+    end
+
+    def to_h
+      {
+        "specversion"     => specversion,
+        "id"              => id,
+        "type"            => type,
+        "source"          => source,
+        "time"            => time,
+        "data"            => Utils::Hash.deep_stringify_keys(data),
+        "datacontenttype" => datacontenttype,
+        "polyntrace"      => Utils::Hash.deep_stringify_keys(polyntrace),
+        "polyndata"       => Utils::Hash.deep_stringify_keys(polyndata),
+      }
+    end
+
+    ##
+    # Get the Event `source` prefixed with reverse domain name
+    def self.full_source(source = nil)
+      root = Polyn.configuration.source_root
+      name = Polyn::Naming.dot_to_colon("#{domain}:#{root}")
+
+      if source
+        Polyn::Naming.validate_source_name!(source)
+        "#{name}:#{Polyn::Naming.dot_to_colon(source)}"
+      else
+        name
+      end
+    end
+
+    ##
+    # Get the Event `type` prefixed with reverse domain name
+    def self.full_type(type)
+      Polyn::Naming.validate_event_type!(type)
+      "#{domain}.#{Polyn::Naming.trim_domain_prefix(type)}"
+    end
+
+    ##
+    # Use a triggering event to build the polyntrace of a new event
+    def self.build_polyntrace(triggered_by)
+      return [] unless triggered_by
+
+      triggered_by.polyntrace.concat([{
+        id:   triggered_by.id,
+        type: triggered_by.type,
+        time: triggered_by.time,
+      }])
+    end
+
+    def self.domain
+      Polyn.configuration.domain
+    end
+  end
+end

data/lib/polyn/naming.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Polyn
+  ##
+  # Methods for formatting and validating names of fields
+  class Naming
+    ##
+    # Convert a dot separated name into a colon separated name
+    def self.dot_to_colon(str)
+      str.gsub(".", ":")
+    end
+
+    ##
+    # Validate that the configured `domain` is in the correct format
+    def self.validate_domain_name!(name)
+      if name.is_a?(String) && name.match?(/\A[a-z0-9]+(?:(?:\.|:)[a-z0-9]+)*\z/)
+        name
+      else
+        raise Polyn::Errors::ConfigurationError,
+          "You must configure the `domain` for Polyn. It must be lowercase, alphanumeric and dot/colon separated, got #{name}"
+      end
+    end
+
+    ##
+    # Validate the `source` name
+    def self.validate_source_name(name)
+      if name.is_a?(String) && name.match?(/\A[a-z0-9]+(?:(?:\.|:)[a-z0-9]+)*\z/)
+        true
+      else
+        "Event source must be lowercase, alphanumeric and dot/colon separated, got #{name}"
+      end
+    end
+
+    ##
+    # Validate the `source` name and raise if invalid
+    def self.validate_source_name!(name)
+      message = validate_source_name(name)
+      if message == true
+        name
+      else
+        raise Polyn::Errors::ValidationError, message
+      end
+    end
+
+    ##
+    # Validate that the configured `source_root` is in the correct format
+    def self.validate_source_root!(name)
+      message = validate_source_name(name)
+      if message == true
+        name
+      else
+        raise Polyn::Errors::ConfigurationError,
+          "You must configure the `source_root` for Polyn. #{message}"
+      end
+    end
+
+    ##
+    # Validate the event type
+    def self.validate_event_type!(name)
+      if name.is_a?(String) && name.match?(/\A[a-z0-9]+(?:\.[a-z0-9]+)*\z/)
+        name
+      else
+        raise Polyn::Errors::ValidationError,
+          "Event types must be lowercase, alphanumeric and dot separated"
+      end
+    end
+
+    ##
+    # Remove the `domain` name from the beginning of a string
+    def self.trim_domain_prefix(str)
+      str = str.sub("#{domain}.", "")
+      str.sub("#{dot_to_colon(domain)}:", "")
+    end
+
+    ##
+    # Create a consumer name from a source and type
+    def self.consumer_name(type, source = nil)
+      validate_event_type!(type)
+      type = trim_domain_prefix(type)
+      type = type.gsub(".", "_")
+
+      root = Polyn.configuration.source_root
+      root = root.gsub(".", "_")
+      root = root.gsub(":", "_")
+
+      if source
+        validate_source_name!(source)
+        source = source.gsub(".", "_")
+        source = source.gsub(":", "_")
+        [root, source, type].join("_")
+      else
+        [root, type].join("_")
+      end
+    end
+
+    def self.domain
+      Polyn.configuration.domain
+    end
+  end
+end

data/lib/polyn/pull_subscriber.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Polyn
+  ##
+  # Wrapper around nats-pure that can validate polyn messages
+  class PullSubscriber
+    ##
+    # @param fields [Object] :nats - Connected NATS instance from `NATS.connect`
+    # @param fields [String] :type - The type of event
+    # @option fields [String] :source - If the `source` portion of the consumer name
+    # is more than the `source_root`
+    def initialize(fields)
+      @nats          = fields.fetch(:nats)
+      @type          = fields.fetch(:type)
+      @type          = Polyn::Naming.trim_domain_prefix(@type)
+      @consumer_name = Polyn::Naming.consumer_name(@type, fields[:source])
+      @stream        = @nats.jetstream.find_stream_name_by_subject(@type)
+      self.class.validate_consumer_exists!(@nats, @stream, @consumer_name)
+      @psub          = @nats.jetstream.pull_subscribe(@type, @consumer_name)
+      @store_name    = store_name(fields)
+    end
+
+    # nats-pure will create a consumer if the one you passed does not exist.
+    # Polyn wants to avoid this functionality and instead encourage
+    # consumer creation in the centralized `events` codebase so that
+    # it's documented, discoverable, and polyn-cli can manage it
+    def self.validate_consumer_exists!(nats, stream, consumer_name)
+      nats.jetstream.consumer_info(stream, consumer_name)
+    rescue NATS::JetStream::Error::NotFound
+      raise Polyn::Errors::ValidationError,
+        "Consumer #{consumer_name} does not exist. Use polyn-cli to create"\
+        "it before attempting to subscribe"
+    end
+
+    # fetch makes a request to be delivered more messages from a pull consumer.
+    #
+    # @param batch [Fixnum] Number of messages to pull from the stream.
+    # @param params [Hash] Options to customize the fetch request.
+    # @option params [Float] :timeout Duration of the fetch request before it expires.
+    # @return [Array<NATS::Msg>]
+    def fetch(batch = 1, params = {})
+      msgs = @psub.fetch(batch, params)
+      msgs.map do |msg|
+        event    = Polyn::Serializers::Json.deserialize(@nats, msg.data, store_name: @store_name)
+        if event.is_a?(Polyn::Errors::Error)
+          msg.term
+          raise event
+        end
+
+        msg.data = event
+        msg
+      end
+    end
+
+    private
+
+    def store_name(opts)
+      opts.fetch(:store_name, Polyn::SchemaStore.store_name)
+    end
+  end
+end

data/lib/polyn/schema_store.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Polyn
+  ##
+  # Persisting and interacting with persisted schemas
+  class SchemaStore
+    STORE_NAME = "POLYN_SCHEMAS"
+
+    ##
+    # Persist a schema. In prod/dev schemas should have already been persisted via
+    # the Polyn CLI.
+    def self.save(nats, type, schema, **opts)
+      json_schema?(schema)
+      kv = nats.jetstream.key_value(store_name(**opts))
+      kv.put(type, JSON.generate(schema))
+    end
+
+    def self.json_schema?(schema)
+      JSONSchemer.schema(schema)
+    end
+
+    def self.get!(nats, type, **opts)
+      result = get(nats, type, **opts)
+      raise result if result.is_a?(Polyn::Errors::SchemaError)
+
+      result
+    end
+
+    def self.get(nats, type, **opts)
+      kv    = nats.jetstream.key_value(store_name(**opts))
+      entry = kv.get(type)
+      entry.value
+    rescue NATS::KeyValue::BucketNotFoundError
+      Polyn::Errors::SchemaError.new(
+        "The Schema Store has not been setup on your NATS server. Make sure you use "\
+        "the Polyn CLI to create it",
+      )
+    rescue NATS::JetStream::Error::NotFound
+      Polyn::Errors::SchemaError.new(
+        "Schema for #{type} does not exist. Make sure it's "\
+        "been added to your `events` codebase and has been loaded "\
+        "into the schema store on your NATS server",
+      )
+    end
+
+    def self.store_name(**opts)
+      opts.fetch(:name, STORE_NAME)
+    end
+  end
+end