|
| 1 | +# Copyright 2024 - 2026 Block, Inc. |
| 2 | +# |
| 3 | +# Use of this source code is governed by an MIT-style |
| 4 | +# license that can be found in the LICENSE file or at |
| 5 | +# https://opensource.org/licenses/MIT. |
| 6 | +# |
| 7 | +# frozen_string_literal: true |
| 8 | + |
| 9 | +require "elastic_graph/constants" |
| 10 | +require "elastic_graph/json_ingestion/schema_definition/factory_extension" |
| 11 | +require "elastic_graph/json_ingestion/schema_definition/state_extension" |
| 12 | + |
| 13 | +module ElasticGraph |
| 14 | + module JSONIngestion |
| 15 | + # Namespace for all JSON Schema schema definition support. |
| 16 | + # |
| 17 | + # {SchemaDefinition::APIExtension} is the primary entry point and should be used as a schema definition extension module. |
| 18 | + module SchemaDefinition |
| 19 | + # Module designed to be extended onto an {ElasticGraph::SchemaDefinition::API} instance |
| 20 | + # to add JSON Schema ingestion serializer capabilities. |
| 21 | + module APIExtension |
| 22 | + # Wires up the JSON ingestion extensions when this module is extended onto an API instance. |
| 23 | + # |
| 24 | + # @param api [ElasticGraph::SchemaDefinition::API] the API instance to extend |
| 25 | + # @return [void] |
| 26 | + # @api private |
| 27 | + def self.extended(api) |
| 28 | + api.state.extend(StateExtension) |
| 29 | + api.factory.extend(FactoryExtension) |
| 30 | + |
| 31 | + api.on_built_in_types do |type| |
| 32 | + if type.name == api.state.type_ref("GeoLocation").to_final_form.name |
| 33 | + # @type var geo_location_type: ElasticGraph::SchemaDefinition::SchemaElements::TypeWithSubfields & SchemaElements::TypeWithSubfieldsExtension |
| 34 | + geo_location_type = _ = type |
| 35 | + names = api.state.schema_elements |
| 36 | + |
| 37 | + # We use `nullable: false` because `GeoLocation` is indexed as a single `geo_point` field, |
| 38 | + # and therefore can't support a `latitude` without a `longitude` or vice-versa. |
| 39 | + latitude = geo_location_type.graphql_fields_by_name.fetch(names.latitude) # : ElasticGraph::SchemaDefinition::SchemaElements::Field & SchemaElements::FieldExtension |
| 40 | + longitude = geo_location_type.graphql_fields_by_name.fetch(names.longitude) # : ElasticGraph::SchemaDefinition::SchemaElements::Field & SchemaElements::FieldExtension |
| 41 | + latitude.json_schema minimum: -90, maximum: 90, nullable: false |
| 42 | + longitude.json_schema minimum: -180, maximum: 180, nullable: false |
| 43 | + end |
| 44 | + end |
| 45 | + end |
| 46 | + |
| 47 | + # Defines the version number of the current JSON schema. Importantly, every time a change is made that impacts the JSON schema |
| 48 | + # artifact, the version number must be incremented to ensure that each different version of the JSON schema is identified by a unique |
| 49 | + # version number. The publisher will then include this version number in published events to identify the version of the schema it |
| 50 | + # was using. This avoids the need to deploy the publisher and ElasticGraph indexer at the same time to keep them in sync. |
| 51 | + # |
| 52 | + # @note While this is an important part of how ElasticGraph is designed to support schema evolution, it can be annoying constantly |
| 53 | + # have to increment this while rapidly changing the schema during prototyping. You can disable the requirement to increment this |
| 54 | + # on every JSON schema change with {#enforce_json_schema_version}. |
| 55 | + # |
| 56 | + # @param version [Integer] current version number of the JSON schema artifact |
| 57 | + # @return [void] |
| 58 | + # @see #enforce_json_schema_version |
| 59 | + # |
| 60 | + # @example Set the JSON schema version to 1 |
| 61 | + # ElasticGraph.define_schema do |schema| |
| 62 | + # schema.json_schema_version 1 |
| 63 | + # end |
| 64 | + def json_schema_version(version) |
| 65 | + state = json_ingestion_state |
| 66 | + |
| 67 | + if !version.is_a?(Integer) || version < 1 |
| 68 | + raise Errors::SchemaError, "`json_schema_version` must be a positive integer. Specified version: #{version}" |
| 69 | + end |
| 70 | + |
| 71 | + if state.json_schema_version |
| 72 | + raise Errors::SchemaError, "`json_schema_version` can only be set once on a schema. Previously-set version: #{state.json_schema_version}" |
| 73 | + end |
| 74 | + |
| 75 | + state.json_schema_version = version |
| 76 | + state.json_schema_version_setter_location = caller_locations(1, 1).to_a.first |
| 77 | + nil |
| 78 | + end |
| 79 | + |
| 80 | + # Configures whether JSON schema artifact dumping enforces the requirement that the JSON schema version is incremented every time |
| 81 | + # dumping the JSON schemas results in a changed artifact. Defaults to `true`. |
| 82 | + # |
| 83 | + # @note Generally speaking, you will want this to be `true` for any ElasticGraph application that is in |
| 84 | + # production as the versioning of JSON schemas is what supports safe schema evolution as it allows |
| 85 | + # ElasticGraph to identify which version of the JSON schema the publishing system was operating on |
| 86 | + # when it published an event. |
| 87 | + # |
| 88 | + # It can be useful to set it to `false` before your application is in production, as you do not want |
| 89 | + # to be forced to bump the version after every single schema change while you are building an initial |
| 90 | + # prototype. |
| 91 | + # |
| 92 | + # @param value [Boolean] whether to require `json_schema_version` to be incremented on changes that impact `json_schemas.yaml` |
| 93 | + # @return [void] |
| 94 | + # @see #json_schema_version |
| 95 | + # |
| 96 | + # @example Disable enforcement during initial prototyping |
| 97 | + # ElasticGraph.define_schema do |schema| |
| 98 | + # # TODO: remove this once we're past the prototyping stage |
| 99 | + # schema.enforce_json_schema_version false |
| 100 | + # end |
| 101 | + def enforce_json_schema_version(value) |
| 102 | + unless value == true || value == false |
| 103 | + raise Errors::SchemaError, "`enforce_json_schema_version` must be a boolean. Specified value: #{value.inspect}" |
| 104 | + end |
| 105 | + |
| 106 | + json_ingestion_state.enforce_json_schema_version = value |
| 107 | + nil |
| 108 | + end |
| 109 | + |
| 110 | + # Defines strictness of the JSON schema validation. By default, the JSON schema will require all fields to be provided by the |
| 111 | + # publisher (but they can be nullable) and will ignore extra fields that are not defined in the schema. Use this method to |
| 112 | + # configure this behavior. |
| 113 | + # |
| 114 | + # @param allow_omitted_fields [bool] Whether nullable fields can be omitted from indexing events. |
| 115 | + # @param allow_extra_fields [bool] Whether extra fields (e.g. beyond fields defined in the schema) can be included in indexing events. |
| 116 | + # @return [void] |
| 117 | + # |
| 118 | + # @note If you allow both omitted fields and extra fields, ElasticGraph's JSON schema validation will allow (and ignore) misspelled |
| 119 | + # field names in indexing events. For example, if the ElasticGraph schema has a nullable field named `parentId` but the publisher |
| 120 | + # accidentally provides it as `parent_id`, ElasticGraph would happily ignore the `parent_id` field entirely, because `parentId` |
| 121 | + # is allowed to be omitted and `parent_id` would be treated as an extra field. Therefore, we recommend that you only set one of |
| 122 | + # these to `true` (or none). |
| 123 | + # |
| 124 | + # @example Allow omitted fields and disallow extra fields |
| 125 | + # ElasticGraph.define_schema do |schema| |
| 126 | + # schema.json_schema_strictness allow_omitted_fields: true, allow_extra_fields: false |
| 127 | + # end |
| 128 | + def json_schema_strictness(allow_omitted_fields: false, allow_extra_fields: true) |
| 129 | + state = json_ingestion_state |
| 130 | + |
| 131 | + unless [true, false].include?(allow_omitted_fields) |
| 132 | + raise Errors::SchemaError, "`allow_omitted_fields` must be true or false" |
| 133 | + end |
| 134 | + |
| 135 | + unless [true, false].include?(allow_extra_fields) |
| 136 | + raise Errors::SchemaError, "`allow_extra_fields` must be true or false" |
| 137 | + end |
| 138 | + |
| 139 | + state.allow_omitted_json_schema_fields = allow_omitted_fields |
| 140 | + state.allow_extra_json_schema_fields = allow_extra_fields |
| 141 | + nil |
| 142 | + end |
| 143 | + |
| 144 | + private |
| 145 | + |
| 146 | + # Returns the API's `state` narrowed to include this gem's `StateExtension`. Centralizes |
| 147 | + # the Steep cast that's needed because Steep can't see the `extend(StateExtension)` applied |
| 148 | + # at runtime in `extended`. |
| 149 | + def json_ingestion_state |
| 150 | + state # : ElasticGraph::SchemaDefinition::State & StateExtension |
| 151 | + end |
| 152 | + end |
| 153 | + end |
| 154 | + end |
| 155 | +end |
0 commit comments