tg_geometry 0.1.0 → 0.3.0

data/ext/tg_geometry/vendor/json/json.h

@@ -0,0 +1,207 @@
+// https://github.com/tidwall/json.c
+//
+// Copyright 2023 Joshua J Baker. All rights reserved.
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+#ifndef JSON_H
+#define JSON_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdbool.h>
+
+enum json_type { 
+    JSON_NULL,
+    JSON_FALSE,
+    JSON_NUMBER,
+    JSON_STRING,
+    JSON_TRUE,
+    JSON_ARRAY,
+    JSON_OBJECT,
+};
+
+struct json { void *priv[4]; };
+
+struct json_valid {
+    bool valid;
+    size_t pos;
+};
+
+// json_valid returns true if the input is valid json data.
+bool json_valid(const char *json_str);
+bool json_validn(const char *json_str, size_t len);
+struct json_valid json_valid_ex(const char *json_str, int opts);
+struct json_valid json_validn_ex(const char *json_str, size_t len, int opts);
+
+// json_parse parses the input data and returns a json value.
+//
+// This function expects that the json is well-formed, and does not validate.
+// Invalid json is safe and will not cause program errors, but it may return
+// unexpected results. If you are consuming JSON from an unpredictable source
+// then you may want to use the 'json_valid' function first.
+// 
+// It's important to note that the resulting 'struct json' is backed by the
+// same memory as json_str, thus a 'struct json' cannot outlive the original
+// json_str. Attempting to use  any of the json_*(struct json...) functions on
+// the result, beyond the lifetime of the originating 'json_str', then it will
+// likely result in a memory fault or some other type of undefined corruption.
+struct json json_parse(const char *json_str);
+struct json json_parsen(const char *json_str, size_t len);
+
+// json_first returns the json's first child.
+//
+// For objects, the key of the first value is returned. For arrays, the first
+// child value is returned. If the input json has no children, or is not an
+// object or array, then a non-existent json value is returned.
+struct json json_first(struct json json);
+
+// json_next returns the json's next child. 
+//
+// This typically follows a 'json_first' call, and is used to iterate over the 
+// children in an object or array. For arrays, each 'json_next' call will
+// return a the next value. For objects, each 'json_next' call alternates over
+// value, key, value  key, value, etc. If there are no more children, then a
+// non-existent json value is returned.
+struct json json_next(struct json json);
+
+// json_exists checks for the existence of json. 
+bool json_exists(struct json json);
+
+// json_type returns the json's type. 
+//
+// Returns one of the following: JSON_NULL, JSON_STRING, JSON_NUMBER,
+// JSON_TRUE, JSON_FALSE, JSON_OBJECT, JSON_ARRAY.
+// For non-existent json, JSON_NULL is returned.
+enum json_type json_type(struct json json);
+
+// json_raw returns the start of the raw json data.
+// 
+// This function may return NULL if the input is non-existent. Also there is
+// no guarentee that this data will be null-terminated C string. If you want to
+// retain this data for longer that the data from the original 'json_parse'
+// call then you should copy it first, such as:
+// 
+//    size_t len = json_raw_length(json);
+//    char *raw = malloc(len+1);
+//    memcpy(raw, json_raw(json), len);
+//    raw[len] = '\0';
+//
+const char *json_raw(struct json json);
+
+// json_raw_length returns the length of the raw json data.
+size_t json_raw_length(struct json json);
+
+// Compare a json's raw data with a C string.
+//
+// This function performs a binary comparison of the characters. It compares
+// each character, one-by-one, of both strings. If they are equal to each
+// other, it continues until the characters differ or until the end of the JSON
+// or a terminating null-character in the C string is reached.
+// Returns -1, 0, +1 for less-than, equal-to, greater-than.
+int json_raw_compare(struct json json, const char *str);
+int json_raw_comparen(struct json json, const char *str, size_t len);
+
+// Compares a json string to the provided C string.
+//
+// This function performs a binary comparison of the characters. It compares
+// each character, one-by-one, of both strings. If they are equal to each
+// other, it continues until the characters differ or until the end of the JSON
+// or a terminating null-character in the C string is reached.
+//
+// If the JSON type is JSON_STRING, then each character that needs to be 
+// unescaped is done so in a streaming manner. ie. without the additional
+// buffering or memory allocations. Of those characters, the ones that are
+// non-ascii codepoints are encoded into their UTF-8 representation, of which
+// those bytes are then compared to the C string.
+// 
+// If the JSON type is not a JSON_STRING, then it performs a binary comparison
+// of the raw JSON to the C string.
+int json_string_compare(struct json json, const char *str);
+int json_string_comparen(struct json json, const char *str, size_t len);
+
+// json_string_length returns the number of characters needed to represent the
+// JSON as a UTF-8 string.
+size_t json_string_length(struct json json);
+
+// json_string_is_escaped returns true if the json is a string that contains
+// an escape sequence.
+bool json_string_is_escaped(struct json json);
+
+// json_string_copy copies a json string into the provided C string buffer.
+//
+// Returns the number of characters, not including the null-terminator, needed
+// to store the JSON into the C string buffer.
+// If the returned length is greater than nbytes-1, then only a parital copy
+// occurred, for example:
+//    
+//    char buf[64];
+//    size_t len = json_string_copy(json, str, sizeof(str));
+//    if (len > sizeof(str)-1) {
+//        // ... copy did not complete ...
+//    }
+//
+size_t json_string_copy(struct json json, char *str, size_t nbytes);
+
+// json_array_get returns the child json element at index. This is to be used
+// on json with the type JSON_ARRAY.
+struct json json_array_get(struct json json, size_t index);
+
+// json_array_count returns the number of elements in a json array.
+size_t json_array_count(struct json json);
+
+// json_object_get returns the json value for its key. This is to be used on
+// json with the type JSON_OBJECT.
+struct json json_object_get(struct json json, const char *key);
+struct json json_object_getn(struct json json, const char *key, size_t len);
+
+// json_get finds json at the provide path.
+//
+// A path is a series of keys separated by a dot.
+//
+//    json_get(json_str, "name");
+//    json_get(json_str, "user.id");
+//
+// The syntax is limited to very basic key names containing only alphanumeric
+// characters, underscores, and dashes. If you need to access keys that have a
+// broader range of characters, you can use the json_object_get and
+// json_array_get functions.
+//
+//    json_str = "{\"notes\": {\"special.info\": \"it's nice outside\"}";
+//    json = json_parse(json_str); 
+//    json = json_object_get(json, "notes"); 
+//    json = json_object_get(json, "special.info");
+//
+struct json json_get(const char *json_str, const char *path);
+struct json json_getn(const char *json_str, size_t len, const char *path);
+
+// json_double returns a json's double value.
+double json_double(struct json json);
+
+// json_int returns a json's int value.
+int json_int(struct json json);
+
+// json_int64 returns a json's int64 value.
+int64_t json_int64(struct json json);
+
+// json_uint64 returns a json's uint64 value.
+uint64_t json_uint64(struct json json);
+
+// json_bool returns a json's boolean value.
+bool json_bool(struct json json);
+
+// json_escape is a utility function for converting a C string into a valid
+// json string. 
+//
+// Returns the number of characters, not including the null-terminator, needed
+// to store the escaped JSON string in the C string buffer.
+// If the returned length is greater than n-1, then only a parital copy
+// occurred. In other words the 
+size_t json_escape(const char *str, char *escaped, size_t n); 
+size_t json_escapen(const char *str, size_t len, char *escaped, size_t n); 
+
+// json_ensure ensures that the json value has been entirely scanned.
+// Only useful for when you need to call json_raw_length on large objects and
+// arrays more than once.
+struct json json_ensure(struct json json);
+
+#endif // JSON_H

data/lib/tg/geometry/active_record_source.rb

@@ -6,52 +6,34 @@ module TG
       module_function
 
       def call(scope, id:, geometry:, batch_size: 1_000)
-        entries = []
-
-        each_record(scope, batch_size: batch_size) do |record|
-          entries << [read_field(record, id), read_field(record, geometry)]
+        enumerator(scope, batch_size: batch_size).map do |record|
+          [read_field(record, id), read_field(record, geometry)]
         end
-
-        entries
       end
 
       def registry_source(scope, id:, geometry:, batch_size: 1_000)
-        proc do
-          TG::Geometry::ActiveRecordSource.call(
-            scope,
-            id: id,
-            geometry: geometry,
-            batch_size: batch_size
-          )
-        end
+        -> { TG::Geometry::ActiveRecordSource.call(scope, id: id, geometry: geometry, batch_size: batch_size) }
       end
 
-      def each_record(scope, batch_size:)
-        if scope.respond_to?(:find_each)
-          scope.find_each(batch_size: batch_size) { |record| yield record }
-        else
-          scope.each { |record| yield record }
+      class << self
+        private
+
+        def enumerator(scope, batch_size:)
+          scope.respond_to?(:find_each) ? scope.find_each(batch_size: batch_size) : scope.each
         end
-      end
-      private_class_method :each_record
 
-      def read_field(record, reader)
-        case reader
-        when Proc
-          reader.call(record)
-        when Symbol, String
-          if record.respond_to?(reader)
-            record.public_send(reader)
-          elsif record.respond_to?(:[])
-            record[reader]
-          else
+        def read_field(record, reader)
+          case reader
+          in Proc then reader.call(record)
+          in Symbol | String if record.respond_to?(reader) then record.public_send(reader)
+          in Symbol | String if record.respond_to?(:[])    then record[reader]
+          in Symbol | String
             raise TG::Geometry::ArgumentError, "record does not expose #{reader.inspect}"
+          else
+            raise TG::Geometry::ArgumentError, "field reader must be Symbol, String, or Proc"
           end
-        else
-          raise TG::Geometry::ArgumentError, "field reader must be Symbol, String, or Proc"
         end
       end
-      private_class_method :read_field
     end
   end
 end

data/lib/tg/geometry/active_record_type.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "tg/geometry"
+
+module TG
+  module Geometry
+    class ActiveRecordType < ActiveModel::Type::Value
+      HEX_PATTERN = /\A[0-9A-Fa-f]+\z/
+
+      def initialize(strict: true)
+        super()
+        @strict = strict
+      end
+
+      def type = :tg_geometry
+
+      def deserialize(value)
+        case value
+        when nil                then nil
+        when TG::Geometry::Geom then value
+        when String             then parse_string(value)
+        else
+          @strict ? raise(TG::Geometry::ArgumentError, "cannot deserialize #{value.class} as TG::Geometry::Geom") : nil
+        end
+      end
+
+      alias cast deserialize
+
+      def serialize(value)
+        case value
+        when nil, String then value
+        else raise TG::Geometry::ArgumentError, "TG::Geometry::ActiveRecordType is read-only in v0.3.0"
+        end
+      end
+
+      private
+
+      def parse_string(str)
+        stripped = str.strip
+
+        if stripped.start_with?("\\x") && stripped[2..].match?(HEX_PATTERN)
+          TG::Geometry.parse_hex(stripped[2..])
+        elsif stripped.match?(HEX_PATTERN)
+          TG::Geometry.parse_hex(stripped)
+        elsif str.encoding == Encoding::ASCII_8BIT
+          TG::Geometry.parse_wkb(str)
+        elsif stripped.start_with?("{")
+          TG::Geometry.parse_geojson(str)
+        else
+          TG::Geometry.parse_wkt(str)
+        end
+      rescue TG::Geometry::ParseError => e
+        raise if @strict
+
+        warn "TG::Geometry::ActiveRecordType: parse failed: #{e.message}"
+        nil
+      end
+    end
+  end
+end

data/lib/tg/geometry/registry.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module TG
   module Geometry
     class Registry
+      extend Forwardable
+
       DEFAULT_INDEX_OPTIONS = {
         via: :geojson,
         strategy: :rtree,
@@ -12,40 +16,23 @@ module TG
 
       class << self
         def source(&block)
-          if block
-            @source = block
-          elsif instance_variable_defined?(:@source)
-            @source
-          elsif superclass.respond_to?(:source)
-            superclass.source
-          end
+          @source = block if block
+          @source || (superclass.source if superclass.respond_to?(:source))
         end
 
         def index_options(**options)
-          if options.empty?
-            inherited = superclass.respond_to?(:index_options) ? superclass.index_options : DEFAULT_INDEX_OPTIONS
-            inherited.merge(@index_options || {}).freeze
-          else
-            @index_options = index_options.merge(options).freeze
-          end
-        end
+          inherited = superclass.respond_to?(:index_options) ? superclass.index_options : DEFAULT_INDEX_OPTIONS
+          return inherited.merge(@index_options || {}).freeze if options.empty?
 
-        def active_record_source(scope, id:, geometry:, batch_size: 1_000)
-          require_relative "active_record_source"
-
-          source do
-            TG::Geometry::ActiveRecordSource.call(
-              scope,
-              id: id,
-              geometry: geometry,
-              batch_size: batch_size
-            )
-          end
+          @index_options = inherited.merge(@index_options || {}, options).freeze
         end
       end
 
       attr_reader :index_options
 
+      def_delegators :index, :size, :bbox, :find_covering, :covering_ids,
+                     :intersecting_rect, :covering_ids_batch_packed
+
       def initialize(entries: nil, source: nil, **index_options)
         @entries = entries
         @source = source
@@ -56,11 +43,7 @@ module TG
 
       def reload!
         new_index = TG::Geometry::Index.build(resolve_entries, **@index_options)
-
-        @reload_mutex.synchronize do
-          @index = new_index
-        end
-
+        @reload_mutex.synchronize { @index = new_index }
         new_index
       end
 
@@ -68,51 +51,17 @@ module TG
         @index || raise(TG::Geometry::Error, "registry index is not loaded; call reload! first")
       end
 
-      def loaded?
-        !@index.nil?
-      end
-
-      def size
-        current_index.size
-      end
-
-      def bbox
-        current_index.bbox
-      end
-
-      def find_covering(lon, lat)
-        current_index.find_covering(lon, lat)
-      end
-
-      def covering_ids(lon, lat)
-        current_index.covering_ids(lon, lat)
-      end
-
-      def intersecting_rect(min_x, min_y, max_x, max_y)
-        current_index.intersecting_rect(min_x, min_y, max_x, max_y)
-      end
-
-      def covering_ids_batch_packed(binary_string)
-        current_index.covering_ids_batch_packed(binary_string)
-      end
+      def loaded? = !@index.nil?
 
       private
 
-      def current_index
-        @index || raise(TG::Geometry::Error, "registry index is not loaded; call reload! first")
-      end
-
       def resolve_entries
-        return @entries unless @entries.nil?
+        return @entries if @entries
 
         callable = @source || self.class.source
         raise TG::Geometry::Error, "registry source is not configured" unless callable
 
-        if callable.respond_to?(:call)
-          instance_exec(&callable)
-        else
-          raise TG::Geometry::Error, "registry source must be callable"
-        end
+        instance_exec(&callable)
       end
     end
   end

data/lib/tg/geometry/version.rb

@@ -2,6 +2,6 @@
 
 module TG
   module Geometry
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/tg/geometry.rb

@@ -4,3 +4,88 @@ require_relative "geometry/version"
 require "tg_geometry_ext_geometry_ext"
 require_relative "geometry/registry"
 require_relative "geometry/active_record_source"
+
+module TG
+  # Fast immutable planar geometry engine with proper indexes and clean
+  # EWKB/PostGIS boundaries. Not a GIS. Not an rgeo replacement.
+  #
+  # All distances and coordinates are in input units. SRID is metadata only;
+  # no reprojection is performed.
+  module Geometry
+    # @!method self.line_string(points, index: :natural, srid: nil)
+    #   @param points [Array<Array<Float>>]
+    #   @param index [:default, :none, :natural, :ystripes]
+    #   @param srid [Integer, nil]
+    #   @return [TG::Geometry::Geom]
+    #
+    # @!method self.polygon(exterior, holes: [], index: :ystripes, srid: nil)
+    #   @param exterior [Array<Array<Float>>]
+    #   @param holes [Array<Array<Array<Float>>>]
+    #   @param index [:default, :none, :natural, :ystripes]
+    #   @param srid [Integer, nil]
+    #   @return [TG::Geometry::Geom]
+    #
+    # @!method self.multi_polygon(polygons, index: :ystripes, srid: nil)
+    #   Each polygon is a Hash with :exterior and optional :holes, or an Array
+    #   shorthand for an exterior with no holes.
+    #   @param polygons [Array<Hash, Array>]
+    #   @return [TG::Geometry::Geom]
+    #
+    # @!method self.parse_wkb(bytes, index: :ystripes)
+    #   Parses WKB or EWKB. SRID is preserved when the EWKB SRID flag is set.
+    #   @return [TG::Geometry::Geom]
+    #
+    # @!method self.parse_hex(hex, index: :ystripes)
+    #   Parses HEXWKB or HEXEWKB. SRID is preserved when the EWKB SRID flag is set.
+    #   @return [TG::Geometry::Geom]
+
+    class Geom
+      # @!method srid
+      #   @return [Integer, nil] SRID metadata; not used for reprojection
+      #
+      # @!method to_ewkb(srid: nil)
+      #   Writes EWKB with the SRID flag set. Uses explicit srid: when provided,
+      #   otherwise Geom#srid. Raises if no SRID is available. to_wkb remains plain.
+      #   @return [String] frozen ASCII-8BIT EWKB string
+    end
+
+    class Index
+      # @!method self.build(entries, via:, strategy:, predicate: :covers, geometry_index: :ystripes)
+      #   predicate: affects only legacy point query methods: find_covering,
+      #   covering_ids(x, y), covering_ids_batch_packed. The *_geom_ids methods
+      #   use their own predicates derived from the method name.
+      #
+      # @!method intersecting_geom_ids(geom)
+      #   Stored geometries for which tg_geom_intersects(stored, query) is true.
+      #   @return [Array<Object>] ids in insertion order
+      #
+      # @!method covering_geom_ids(geom)
+      #   Stored geometries for which tg_geom_covers(stored, query) is true.
+      #   Direction: stored covers query. Boundary points are covered.
+      #   @return [Array<Object>] ids in insertion order
+      #
+      # @!method containing_geom_ids(geom)
+      #   Stored geometries for which tg_geom_contains(stored, query) is true.
+      #   Direction: stored contains query. Boundary points are not contained.
+      #   @return [Array<Object>] ids in insertion order
+    end
+
+    class Line
+      # @!method nearest_segment(x, y)
+      #   @return [TG::Geometry::NearestSegment, nil] planar Euclidean
+    end
+
+    class Ring
+      # @!method nearest_segment(x, y)
+      #   @return [TG::Geometry::NearestSegment, nil] planar Euclidean
+    end
+
+    # Result of Line#nearest_segment / Ring#nearest_segment.
+    class NearestSegment
+      # @!attribute [r] segment   @return [TG::Geometry::Segment]
+      # @!attribute [r] index     @return [Integer]
+      # @!attribute [r] distance  @return [Float] planar Euclidean in input units
+      # @!attribute [r] point     @return [Array(Float, Float)] projection
+    end
+  end
+end

data/script/vendor_libs.rb

@@ -26,6 +26,14 @@ PINS = {
     sha256: "4afc86cbd3abe03730206031a5aff5b8b29d37b055fc356052f6f06e1d1f9a61",
     target: "rtree",
     files: %w[rtree.c rtree.h LICENSE README.md]
+  },
+  json: {
+    repo: "https://github.com/tidwall/json.c.git",
+    ref: "main",
+    commit: "4aaf99b5c08e4e1364f97500fe5c5d5a2617b4a6",
+    sha256: "059393302de9325ab6ccf79c298234f2b688a59d138103305da317d2d0176fe2",
+    target: "json",
+    files: %w[json.c json.h LICENSE]
   }
 }.freeze
 
@@ -160,9 +168,13 @@ def write_manifest(results)
   File.utime(NORMALIZED_MTIME, NORMALIZED_MTIME, MANIFEST_PATH)
 end
 
-def expected_vendor_results
+def expected_vendor_results(manifest = nil)
+  manifest ||= parse_kv_file(MANIFEST_PATH)
+
   PINS.each_with_object({}) do |(name, pin), results|
-    results[name] = pin.merge(tree_sha256: pin.fetch(:sha256))
+    manifest_sha = manifest["#{name}_tree_sha256"]
+    tree_sha = pin.fetch(:sha256) || manifest_sha
+    results[name] = pin.merge(tree_sha256: tree_sha)
   end
 end
 
@@ -186,6 +198,7 @@ end
 
 def verify_vendor_tree
   failures = []
+  manifest = parse_kv_file(MANIFEST_PATH)
 
   PINS.each do |name, pin|
     target = File.join(VENDOR_DIR, pin.fetch(:target))
@@ -207,12 +220,15 @@ def verify_vendor_tree
     next unless failures.none? { |failure| failure.start_with?("#{name}:") }
 
     actual_sha256 = tree_sha256_for(target)
-    expected_sha256 = pin.fetch(:sha256)
-    failures << "#{name}: tree_sha256 mismatch: expected #{expected_sha256}, got #{actual_sha256}" unless actual_sha256 == expected_sha256
+    expected_sha256 = pin.fetch(:sha256) || manifest["#{name}_tree_sha256"]
+    if expected_sha256.nil? || expected_sha256.empty?
+      failures << "#{name}: tree_sha256 missing from manifest"
+    elsif actual_sha256 != expected_sha256
+      failures << "#{name}: tree_sha256 mismatch: expected #{expected_sha256}, got #{actual_sha256}"
+    end
   end
 
-  expected_results = expected_vendor_results
-  manifest = parse_kv_file(MANIFEST_PATH)
+  expected_results = expected_vendor_results(manifest)
   if manifest.empty?
     failures << "manifest: missing #{MANIFEST_PATH}"
   else

data/spec/active_record_type_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "tg/geometry/active_record_type"
+
+RSpec.describe TG::Geometry::ActiveRecordType do
+  let(:type) { described_class.new }
+  let(:ewkb) { TG::Geometry.parse_wkt("POINT (1 2)").to_ewkb(srid: 4326) }
+  let(:geom) { TG::Geometry.parse_wkb(ewkb) }
+
+  it "deserializes supported read shapes" do
+    expect(type.type).to eq(:tg_geometry)
+    expect(type.deserialize(nil)).to be_nil
+    expect(type.deserialize(geom)).to equal(geom)
+    expect(type.deserialize(ewkb).srid).to eq(4326)
+    expect(type.deserialize(ewkb.unpack1("H*")).srid).to eq(4326)
+    expect(type.deserialize("\\x#{ewkb.unpack1('H*')}").srid).to eq(4326)
+    expect(type.deserialize('{"type":"Point","coordinates":[1,2]}').srid).to be_nil
+    expect(type.deserialize("POINT (1 2)").srid).to be_nil
+  end
+
+  it "detects ASCII-8BIT hex before WKB fallback" do
+    hex = ewkb.unpack1("H*").b
+
+    expect(type.deserialize(hex).srid).to eq(4326)
+  end
+
+  it "is strict by default and can warn+nil in non-strict mode" do
+    expect { type.deserialize("not geometry") }.to raise_error(TG::Geometry::ParseError)
+
+    non_strict = described_class.new(strict: false)
+    expect { expect(non_strict.deserialize("not geometry")).to be_nil }
+      .to output(/parse failed/).to_stderr
+  end
+
+  it "is read-only on serialize" do
+    expect(type.serialize(nil)).to be_nil
+    expect(type.serialize("raw")).to eq("raw")
+    expect { type.serialize(geom) }.to raise_error(TG::Geometry::ArgumentError)
+  end
+
+  it "uses cast as deserialize" do
+    expect(type.cast(ewkb).srid).to eq(4326)
+  end
+end

data/spec/{expansion_a_auto_strategy_spec.rb → auto_strategy_spec.rb}

@@ -2,7 +2,7 @@
 
 require "spec_helper"
 
-RSpec.describe "Expansion Block A auto strategy status" do
+RSpec.describe "Auto strategy status" do
   it "does not expose :auto in the first public release" do
     entries = [[1, '{"type":"Polygon","coordinates":[[[0,0],[1,0],[1,1],[0,1],[0,0]]]}']]