Skip to content

A platform for community discussion. Free, open, simple.

24.4 KB
Raw Blame
# frozen_string_literal: true

require "json_schemer"
require_relative "schema/graph_resolver"

module DiscourseWorkflows
  module Schema
    DRAFT_URI = "https://json-schema.org/draft/2020-12/schema"
    MODES = %i[replace passthrough merge union].freeze

    def self.entity(name, properties, description)
      {
        "$schema" => DRAFT_URI,
        "type" => "object",
        "properties" => {
          name => {
            "type" => "object",
            "description" => description,
            "properties" => properties,
          },
        },
      }.freeze
    end

    def self.document(properties)
      { "$schema" => DRAFT_URI, "type" => "object", "properties" => properties }.freeze
    end

    def self.nullable_user(description)
      { "type" => %w[object null], "description" => description, "properties" => USER_PROPERTIES }
    end

    def self.entity_extension(name, properties)
      {
        "$schema" => DRAFT_URI,
        "type" => "object",
        "properties" => {
          name => {
            "type" => "object",
            "properties" => properties,
          },
        },
      }.freeze
    end

    TOPIC_PROPERTIES = JSON.parse(<<~JSON).freeze
      {
        "id": { "type": "integer" },
        "title": { "type": "string" },
        "fancy_title": { "type": "string" },
        "fancy_title_localized": { "type": "boolean", "description": "Whether fancy_title is a translation" },
        "slug": { "type": "string" },
        "url": { "type": "string", "description": "Absolute URL of the topic" },
        "archetype": { "type": "string", "description": "regular for topics, private_message for PMs" },
        "posts_count": { "type": "integer" },
        "category_id": { "type": ["integer", "null"] },
        "user_id": { "type": "integer" },
        "username": { "type": ["string", "null"], "description": "Username of the topic author" },
        "locale": { "type": ["string", "null"], "description": "Content locale, null until set by the author or detected" },
        "tags": {
          "type": "array",
          "x-optional": true,
          "items": {
            "type": "object",
            "properties": {
              "id": { "type": "integer" },
              "name": { "type": "string" },
              "slug": { "type": "string" }
            }
          }
        },
        "first_post_id": { "type": ["integer", "null"] },
        "visible": { "type": "boolean" },
        "visibility_reason_id": { "type": "integer", "x-optional": true },
        "closed": { "type": "boolean" },
        "archived": { "type": "boolean" },
        "created_at": { "type": "string", "format": "date-time" },
        "last_posted_at": { "type": ["string", "null"], "format": "date-time" },
        "bumped_at": { "type": ["string", "null"], "format": "date-time" }
      }
    JSON

    POST_PROPERTIES = JSON.parse(<<~JSON).freeze
      {
        "id": { "type": "integer" },
        "raw": { "type": "string" },
        "raw_truncated": { "type": "boolean", "x-optional": true },
        "raw_original_length": { "type": "integer", "x-optional": true },
        "cooked": { "type": "string", "x-optional": true },
        "cooked_truncated": { "type": "boolean", "x-optional": true },
        "cooked_original_length": { "type": "integer", "x-optional": true },
        "post_number": { "type": "integer" },
        "post_type": { "type": "integer" },
        "reply_to_post_number": { "type": ["integer", "null"] },
        "reply_to_post_id": { "type": ["integer", "null"] },
        "reply_to_username": { "type": ["string", "null"] },
        "topic_id": { "type": "integer" },
        "topic_slug": { "type": "string" },
        "topic_title": { "type": "string" },
        "post_url": { "type": "string", "description": "Relative URL of the post" },
        "url": { "type": "string", "description": "Absolute URL of the post" },
        "category_id": { "type": ["integer", "null"] },
        "category_name": { "type": ["string", "null"] },
        "category_slug": { "type": ["string", "null"] },
        "user_id": { "type": "integer" },
        "username": { "type": "string" },
        "created_at": { "type": "string", "format": "date-time" },
        "updated_at": { "type": "string", "format": "date-time" },
        "excerpt": { "type": "string" },
        "like_count": { "type": "integer" },
        "reply_count": { "type": "integer" },
        "score": { "type": ["number", "null"] },
        "tags": { "type": "array", "items": { "type": "string" } },
        "upload_ids": { "type": "array", "items": { "type": "integer" } },
        "locale": { "type": ["string", "null"], "description": "Content locale, null until set by the author or detected" }
      }
    JSON

    USER_PROPERTIES = JSON.parse(<<~JSON).freeze
      {
        "id": { "type": "integer" },
        "username": { "type": "string" },
        "name": { "type": ["string", "null"] },
        "trust_level": { "type": "integer" },
        "trust_level_name": { "type": "string" },
        "admin": { "type": "boolean" },
        "moderator": { "type": "boolean" },
        "staff": { "type": "boolean" },
        "created_at": { "type": "string", "format": "date-time" },
        "approved": { "type": "boolean" },
        "silenced": { "type": "boolean" },
        "suspended": { "type": "boolean" },
        "uploaded_avatar_id": { "type": ["integer", "null"] },
        "avatar_template": { "type": "string" },
        "locale": { "type": "string", "description": "Interface locale, the site default when the user has not chosen one" }
      }
    JSON

    BASIC_GROUP_PROPERTIES = JSON.parse(<<~JSON).freeze
      {
        "id": { "type": "integer" },
        "name": { "type": "string" },
        "full_name": { "type": ["string", "null"] },
        "automatic": { "type": "boolean" }
      }
    JSON

    GROUP_PROPERTIES = BASIC_GROUP_PROPERTIES.merge(JSON.parse(<<~JSON)).freeze
      {
        "user_count": { "type": "integer" },
        "title": { "type": ["string", "null"] },
        "visibility_level": { "type": "integer" },
        "members_visibility_level": { "type": "integer" },
        "mentionable_level": { "type": "integer" },
        "messageable_level": { "type": "integer" },
        "primary_group": { "type": "boolean" },
        "grant_trust_level": { "type": ["integer", "null"] },
        "public_admission": { "type": "boolean" },
        "public_exit": { "type": "boolean" },
        "allow_membership_requests": { "type": "boolean" },
        "default_notification_level": { "type": "integer" },
        "membership_request_template": { "type": ["string", "null"] },
        "can_see_members": { "type": "boolean" },
        "publish_read_state": { "type": "boolean" },
        "flair_url": { "type": ["string", "null"] },
        "flair_bg_color": { "type": ["string", "null"] },
        "flair_color": { "type": ["string", "null"] },
        "bio_cooked": { "type": ["string", "null"] },
        "bio_excerpt": { "type": ["string", "null"] }
      }
    JSON

    TOPIC_LIST_ITEM_SCHEMA = entity("topic", TOPIC_PROPERTIES, "Workflow topic payload")
    POST_SCHEMA = entity("post", POST_PROPERTIES, "DiscourseWorkflows::PostSerializer payload")
    USER_SCHEMA = entity("user", USER_PROPERTIES, "Basic safe user attributes")
    ACTOR_SCHEMA = document("actor" => nullable_user("User who performed the action"))
    POST_AUTHOR_SCHEMA = document("user" => nullable_user("Post author"))
    TOPIC_AUTHOR_SCHEMA = document("user" => nullable_user("Topic author"))
    ASSIGNEE_PROPERTIES = {
      "type" => "object",
      "properties" => {
        "type" => {
          "type" => %w[string null],
        },
        "user" => {
          "type" => "object",
          "x-optional" => true,
          "properties" => USER_PROPERTIES,
        },
        "group" => {
          "type" => "object",
          "x-optional" => true,
          "properties" => BASIC_GROUP_PROPERTIES,
        },
      },
    }.freeze
    IP_LOCATION_PROPERTIES = JSON.parse(<<~JSON).freeze
      {
        "type": ["object", "null"],
        "description": "Derived on demand from the MaxMind databases, null when unavailable",
        "properties": {
          "country": { "type": "string" },
          "country_code": { "type": "string" },
          "region": { "type": ["string", "null"] },
          "city": { "type": ["string", "null"] },
          "location": { "type": "string" },
          "latitude": { "type": ["number", "null"] },
          "longitude": { "type": ["number", "null"] },
          "asn": { "type": ["integer", "null"] },
          "organization": { "type": ["string", "null"] }
        }
      }
    JSON

    USER_ACTION_PROPERTIES =
      JSON
        .parse(<<~JSON)
          {
            "title": { "type": ["string", "null"] },
            "bio_raw": { "type": ["string", "null"] },
            "website": { "type": ["string", "null"] },
            "location": { "type": ["string", "null"] },
            "profile_background_upload_id": { "type": ["integer", "null"] },
            "card_background_upload_id": { "type": ["integer", "null"] },
            "manual_locked_trust_level": { "type": ["integer", "null"] },
            "trust_level_locked": { "type": "boolean" },
            "user_fields": { "type": "object" }
          }
        JSON
        .merge(
          "groups" => {
            "type" => "array",
            "items" => {
              "type" => "object",
              "properties" => BASIC_GROUP_PROPERTIES,
            },
          },
        )
        .freeze

    USER_STATS_PROPERTIES = JSON.parse(<<~JSON).freeze
          {
            "stats": {
              "type": ["object", "null"],
              "properties": {
                "topics_entered": { "type": "integer" },
                "posts_read_count": { "type": "integer" },
                "time_read": { "type": "integer" },
                "days_visited": { "type": "integer" },
                "post_count": { "type": "integer" },
                "topic_count": { "type": "integer" },
                "likes_given": { "type": "integer" },
                "likes_received": { "type": "integer" },
                "first_post_created_at": { "type": ["string", "null"], "format": "date-time" }
              }
            }
          }
        JSON

    USER_EXTENSION_PROPERTIES = {
      "stats" => USER_STATS_PROPERTIES,
      "external_ids" =>
        JSON.parse(
          '{ "external_id": { "type": ["string", "null"] }, "external_ids": { "type": "object" } }',
        ).freeze,
      "emails" =>
        JSON.parse(
          '{ "email": { "type": ["string", "null"] }, "secondary_emails": { "type": "array", "items": { "type": "string" } } }',
        ).freeze,
      "ips" => {
        "registration_ip_address" => {
          "type" => %w[string null],
        },
        "registration_location" => IP_LOCATION_PROPERTIES,
        "ip_address" => {
          "type" => %w[string null],
        },
        "last_location" => IP_LOCATION_PROPERTIES,
      }.freeze,
    }.freeze

    USER_ACTION_SCHEMA =
      entity(
        "user",
        USER_PROPERTIES.merge(USER_ACTION_PROPERTIES),
        "Discourse user lookup/update payload",
      )

    USER_EXTENSION_SCHEMAS =
      USER_EXTENSION_PROPERTIES
        .transform_values { |properties| entity_extension("user", properties) }
        .freeze
    BASIC_GROUP_SCHEMA =
      entity("group", BASIC_GROUP_PROPERTIES, "Group involved in the membership event")
    GROUP_SCHEMA = entity("group", GROUP_PROPERTIES, "WebHookGroupSerializer payload")
    GROUP_MEMBERSHIP_SCHEMA =
      entity("group_membership", JSON.parse(<<~JSON), "Group membership check result")
        {
          "group_id": { "type": "integer" },
          "group_name": { "type": "string" },
          "user_id": { "type": "integer" },
          "username": { "type": "string" },
          "in_group": { "type": "boolean" }
        }
      JSON
    WEBHOOK_REQUEST_SCHEMA = document(JSON.parse(<<~JSON))
          {
            "body": {},
            "headers": { "type": "object" },
            "params": { "type": "object" },
            "query": { "type": "object" },
            "method": { "type": "string" },
            "webhook_url": { "type": "string" },
            "raw_body": { "type": "string", "x-optional": true }
          }
        JSON

    def self.group_membership_event(action)
      document(
        USER_SCHEMA
          .fetch("properties")
          .merge(BASIC_GROUP_SCHEMA.fetch("properties"))
          .merge(
            "membership" => {
              "type" => "object",
              "description" => "Group membership event metadata",
              "properties" => {
                "automatic" => {
                  "type" => %w[boolean null],
                },
                "action" => {
                  "const" => action,
                },
              },
            },
          ),
      )
    end

    USER_ADDED_TO_GROUP_SCHEMA = group_membership_event("added")
    USER_REMOVED_FROM_GROUP_SCHEMA = group_membership_event("removed")

    USER_EVENT_SCHEMA =
      entity(
        "user",
        USER_PROPERTIES.merge(
          "staged" => {
            "type" => "boolean",
          },
          "created_at" => {
            "type" => "string",
            "format" => "date-time",
          },
        ),
        "User account event payload",
      )

    USER_UPDATED_EVENT_SCHEMA =
      document(
        USER_EVENT_SCHEMA.fetch("properties").merge(
          "changed" => {
            "type" => %w[array null],
            "description" =>
              "Which parts of the profile changed, or null when the update did not report it",
            "items" => {
              "type" => "string",
            },
          },
        ),
      )

    USER_SEEN_SCHEMA =
      document(
        USER_SCHEMA.fetch("properties").merge(
          "seen" => {
            "type" => "object",
            "description" => "User seen event details",
            "properties" => {
              "first_seen" => {
                "type" => "boolean",
              },
              "current_seen_at" => {
                "type" => %w[string null],
                "format" => "date-time",
              },
              "previous_seen_at" => {
                "type" => %w[string null],
                "format" => "date-time",
              },
              "seconds_since_previous_seen" => {
                "type" => %w[integer null],
              },
            },
          },
        ),
      )

    REVIEWABLE_PROPERTIES = {
      "target_user" => nullable_user("User the reviewable is about"),
      "created_by" => nullable_user("User who flagged or queued the item"),
    }.merge(JSON.parse(<<~JSON)).freeze
      {
        "id": { "type": "integer" },
        "type": { "type": "string" },
        "status": { "type": "string" },
        "target_type": { "type": ["string", "null"] },
        "target_id": { "type": ["integer", "null"] },
        "topic_id": { "type": ["integer", "null"] },
        "category_id": { "type": ["integer", "null"] },
        "chat_channel_id": { "type": ["integer", "null"] },
        "score": { "type": "number", "description": "Total review score. Flag scores are added after the item is queued, so this is usually 0 when the item is created" },
        "potential_spam": { "type": "boolean" },
        "url": { "type": "string", "description": "Absolute URL of the item in the review queue" },
        "created_at": { "type": ["string", "null"], "format": "date-time" }
      }
    JSON

    REVIEWABLE_EVENT_SCHEMA =
      entity("reviewable", REVIEWABLE_PROPERTIES, "Review queue item payload")

    TAG_PROPERTIES = JSON.parse(<<~JSON).freeze
      {
        "id": { "type": "integer" },
        "name": { "type": "string" },
        "slug": { "type": "string" },
        "topic_count": { "type": "integer" },
        "staff": { "type": "boolean" },
        "description": { "type": ["string", "null"] },
        "description_cooked": { "type": ["string", "null"] }
      }
    JSON

    TAG_SCHEMA = entity("tag", TAG_PROPERTIES, "Tag created by Discourse")

    BADGE_PROPERTIES = JSON.parse(<<~JSON).freeze
      {
        "id": { "type": "integer" },
        "name": { "type": "string" },
        "description": { "type": ["string", "null"] },
        "badge_type_id": { "type": "integer" },
        "icon": { "type": ["string", "null"] },
        "image_url": { "type": ["string", "null"] },
        "grant_count": { "type": "integer" },
        "system": { "type": "boolean" },
        "multiple_grant": { "type": "boolean" }
      }
    JSON

    BADGE_SCHEMA = entity("badge", BADGE_PROPERTIES, "Badge involved in the grant event")
    BADGE_GRANTED_SCHEMA =
      document(USER_SCHEMA.fetch("properties").merge(BADGE_SCHEMA.fetch("properties")))

    class << self
      def normalize(schema)
        return {} if schema.blank?

        raise ArgumentError, "Output schema must be a JSON Schema object" unless schema.is_a?(Hash)

        schema = schema.deep_stringify_keys
        unless schema["$schema"] == DRAFT_URI
          raise ArgumentError, "Output schema must declare JSON Schema Draft 2020-12"
        end
        unless JSONSchemer.valid_schema?(schema)
          raise ArgumentError, "Output schema is not valid JSON Schema Draft 2020-12"
        end

        schema
      end

      def merge(*schemas)
        schemas = schemas.flatten.map { |schema| stringify(schema) }.reject(&:empty?)
        schemas.reduce({}) { |combined, schema| merge_pair(combined, schema) }
      end

      def unknown?(schema)
        stringify(schema).empty?
      end

      def union(*schemas)
        schemas = schemas.flatten.map { |schema| stringify(schema) }
        return {} if schemas.empty? || schemas.any? { |schema| unknown?(schema) }

        branches = schemas.flat_map { |schema| union_branches(schema) }.uniq
        return branches.first if branches.one?

        { "$schema" => DRAFT_URI, "anyOf" => branches }
      end

      def augment(schema, *extensions)
        extensions = extensions.flatten.map { |extension| stringify(extension) }.reject(&:empty?)
        return schema if extensions.empty?

        schema = stringify(schema)
        if any_of_wrapper?(schema)
          return union(*union_branches(schema).map { |branch| augment(branch, extensions) })
        end

        extensions.reduce(schema) { |merged, extension| merge_pair(merged, extension) }
      end

      def resolve(schema, mode:, input_schema: {})
        mode = mode&.to_sym
        raise ArgumentError, "Unknown output schema mode: #{mode.inspect}" if MODES.exclude?(mode)

        case mode
        when :passthrough
          input_schema
        when :union
          union(input_schema, schema)
        when :merge
          overlay(stringify(input_schema), stringify(schema))
        else
          schema
        end
      end

      def resolve_graph(nodes, connections)
        GraphResolver.call(nodes, connections)
      end

      def infer(value)
        return {} unless value.is_a?(Hash) && value.present?

        infer_value(value)
      end

      def expression_value?(value)
        value.is_a?(String) && value.start_with?("=")
      end

      # :indeterminate means a rule is anchored to an expression-valued parameter,
      # so the target must neither be dropped nor have its requirements enforced.
      def display_state(display_options, configuration)
        display_options = normalize_options(display_options)
        show_rules = display_options["show"]
        hide_rules = display_options["hide"]
        return :visible if show_rules.blank? && hide_rules.blank?

        configuration = normalize_configuration(configuration)
        indeterminate = false

        if show_rules.present?
          outcome = rules_outcome(show_rules, configuration)
          return :hidden if outcome == false
          indeterminate ||= outcome == :unknown
        end

        if hide_rules.present?
          outcome = rules_outcome(hide_rules, configuration)
          return :hidden if outcome == true
          indeterminate ||= outcome == :unknown
        end

        indeterminate ? :indeterminate : :visible
      end

      def visible?(display_options, configuration)
        display_state(display_options, configuration) != :hidden
      end

      def definitely_visible?(display_options, configuration)
        display_state(display_options, configuration) == :visible
      end

      private

      def stringify(schema)
        schema.respond_to?(:to_h) ? schema.to_h.deep_stringify_keys : {}
      end

      def overlay(input_schema, declared_schema)
        return declared_schema if input_schema.empty?
        return input_schema if declared_schema.empty?

        if any_of_wrapper?(input_schema)
          return(
            union(
              *input_schema["anyOf"].map { |branch| overlay(stringify(branch), declared_schema) },
            )
          )
        end

        merged = input_schema.merge(declared_schema)
        return merged unless object_schema?(input_schema) && object_schema?(declared_schema)

        merged["properties"] = (input_schema["properties"] || {}).merge(
          declared_schema["properties"] || {},
        )

        required = Array(input_schema["required"]) | Array(declared_schema["required"])
        required.empty? ? merged.delete("required") : merged["required"] = required
        merged
      end

      def merge_pair(left, right)
        merged = left.merge(right)
        return merged unless object_schema?(left) && object_schema?(right)

        merged["properties"] = (left["properties"] || {}).merge(
          right["properties"] || {},
        ) do |_name, left_value, right_value|
          if object_schema?(left_value) && object_schema?(right_value)
            merge_pair(left_value, right_value)
          else
            right_value
          end
        end

        required = Array(left["required"]) | Array(right["required"])
        required.empty? ? merged.delete("required") : merged["required"] = required
        merged
      end

      def object_schema?(schema)
        schema.is_a?(Hash) && Array(schema["type"]).include?("object")
      end

      def union_branches(schema)
        any_of_wrapper?(schema) ? schema["anyOf"] : [schema]
      end

      def any_of_wrapper?(schema)
        (schema.keys - ["$schema"]) == ["anyOf"]
      end

      def infer_value(value)
        case value
        when Hash
          {
            "type" => "object",
            "properties" =>
              value.to_h.transform_keys(&:to_s).transform_values { |child| infer_value(child) },
          }
        when Array
          item_schemas = value.map { |child| infer_value(child) }.uniq
          schema = { "type" => "array" }
          if item_schemas.any?
            schema["items"] = item_schemas.one? ? item_schemas.first : { "anyOf" => item_schemas }
          end
          schema
        when Integer
          { "type" => "integer" }
        when Numeric
          { "type" => "number" }
        when TrueClass, FalseClass
          { "type" => "boolean" }
        when NilClass
          { "type" => "null" }
        else
          { "type" => "string" }
        end
      end

      def normalize_options(options)
        return {} if options.blank?

        options.to_h.deep_stringify_keys
      end

      # Rules only anchor on top-level keys, so a shallow pass avoids deep-copying
      # the whole configuration on every visibility check.
      def normalize_configuration(configuration)
        return {} if configuration.blank?

        configuration.to_h.stringify_keys
      end

      def rules_outcome(rules, configuration)
        unknown = false

        rules.each do |field_name, expected|
          value = configuration[field_name.to_s]
          if expression_value?(value)
            unknown = true
            next
          end

          return false unless matches_rule?(expected, value)
        end

        unknown ? :unknown : true
      end

      def matches_rule?(expected, value)
        conditions = expected.is_a?(Array) ? expected : [expected]
        conditions.any? { |condition| matches_condition?(condition, value) }
      end

      def matches_condition?(condition, value)
        operator = condition.is_a?(Hash) ? condition["condition"] : nil
        if operator.blank?
          return value.include?(condition) if value.is_a?(Array) && !condition.is_a?(Array)
          return condition == value
        end
        return value != operator["not"] if operator.key?("not")

        if operator.key?("exists")
          return operator["exists"] ? !empty_value?(value) : empty_value?(value)
        end

        false
      end

      def empty_value?(value)
        return true if value.nil? || value == ""
        return value.empty? if value.is_a?(Array)

        false
      end
    end
  end
end