field_struct-avro 1.0.0.pre1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,10 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FieldStruct
4
+ # Apache Avro for field_struct classes.
5
+ module Avro
6
+ # The gem version.
7
+ # @return [::String]
8
+ VERSION = '1.0.0.pre1'
9
+ end
10
+ end
@@ -0,0 +1,33 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FieldStruct
4
+ module Avro
5
+ # Turns the +writer_schema:+ argument of +decode+ into the JSON text and the schema the avro gem parsed (AV-B38).
6
+ module WriterSchema
7
+ module_function
8
+
9
+ # @param value [::Hash, ::String, ::Avro::Schema] a Hash with String keys, a JSON String or a parsed schema
10
+ # @return [::String] the schema as JSON text
11
+ # @raise [::ArgumentError] for any other form
12
+ def text(value)
13
+ case value
14
+ when ::Hash then Oj.dump(value, mode: :compat)
15
+ when ::String then value
16
+ when ::Avro::Schema then value.to_s
17
+ else
18
+ raise ::ArgumentError, 'FieldStruct::Avro.decode: writer_schema: expects a Hash, a JSON String or an Avro::Schema, ' \
19
+ "got #{value.class}"
20
+ end
21
+ end
22
+
23
+ # @param text [::String] JSON text
24
+ # @return [::Avro::Schema]
25
+ # @raise [::ArgumentError] when the text is not JSON or not a valid Avro schema
26
+ def parse(text)
27
+ ::Avro::Schema.parse(text)
28
+ rescue ::StandardError => e
29
+ raise ::ArgumentError, "FieldStruct::Avro.decode: writer_schema: isn't a valid Avro schema (#{e.class}: #{e.message})"
30
+ end
31
+ end
32
+ end
33
+ end
@@ -0,0 +1,23 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FieldStruct
4
+ module Avro
5
+ # Puts a decoded time back in the field's +zone:+ (AV-B26); Avro times carry no offset and the avro gem returns UTC.
6
+ module Zone
7
+ module_function
8
+
9
+ # @param time [::Object] a Time; anything else is returned as given
10
+ # @param zone [::Object] the field's +zone:+; anything but a String leaves the time as it is
11
+ # @return [::Object] a new Time at the same instant
12
+ def apply(time, zone)
13
+ return time unless time.is_a?(::Time) && zone.is_a?(::String)
14
+ return time.getutc if zone == 'UTC'
15
+ return time.getlocal(zone) unless zone.include?('/')
16
+
17
+ require 'tzinfo'
18
+ offset = TZInfo::Timezone.get(zone).period_for_utc(time.getutc).utc_total_offset
19
+ time.getlocal(offset)
20
+ end
21
+ end
22
+ end
23
+ end
@@ -0,0 +1,138 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'bigdecimal'
4
+ require 'stringio'
5
+ require 'avro'
6
+ require 'oj'
7
+ require 'field_struct'
8
+
9
+ unless defined?(FieldStruct::Introspection)
10
+ raise LoadError, 'field_struct-avro needs FieldStruct::Introspection (field_struct >= 1.0.0.pre1); ' \
11
+ 'upgrade field_struct or check that its version is loaded'
12
+ end
13
+
14
+ require_relative 'avro/version'
15
+ require_relative 'avro/check'
16
+ require_relative 'avro/options'
17
+ require_relative 'avro/trail'
18
+ require_relative 'avro/names'
19
+ require_relative 'avro/defaults'
20
+ require_relative 'avro/scalar_types'
21
+ require_relative 'avro/union_rules'
22
+ require_relative 'avro/site'
23
+ require_relative 'avro/stamp'
24
+ require_relative 'avro/entry'
25
+ require_relative 'avro/schema_builder'
26
+ require_relative 'avro/value_json'
27
+ require_relative 'avro/zone'
28
+ require_relative 'avro/datum_writer'
29
+ require_relative 'avro/datum_reader'
30
+ require_relative 'avro/bytes_reader'
31
+ require_relative 'avro/writer_schema'
32
+ require_relative 'avro/resolution'
33
+ require_relative 'avro/projection'
34
+ require_relative 'avro/evolution'
35
+ require_relative 'avro/cache'
36
+ require_relative 'avro/methods'
37
+
38
+ # The field_struct namespace.
39
+ module FieldStruct
40
+ # Apache Avro for field_struct classes: record schemas, datums and the binary encoding.
41
+ module Avro
42
+ # The accepted precisions of +:time+ and +:datetime+ fields.
43
+ # @return [::Array<::Symbol>]
44
+ TIMESTAMPS = %i[micros nanos millis].freeze
45
+
46
+ class << self
47
+ # The Avro record schema of a struct class.
48
+ #
49
+ # @param klass [::Class<FieldStruct::Base>] a named +FieldStruct::Base+ subclass
50
+ # @param serialization [::Symbol, ::String] the +serialize+ format whose names become Avro field names
51
+ # @param timestamp [::Symbol] +:micros+, +:nanos+ or +:millis+
52
+ # @return [::Hash{::String=>::Object}] a fresh Hash
53
+ # @raise [::ArgumentError] for a bad argument, an unmappable field or a schema the avro gem rejects
54
+ def schema(klass, serialization: :avro, timestamp: :micros)
55
+ serialization = Check.call(klass, timestamp: timestamp, serialization: serialization)
56
+ Cache.reader(klass, serialization, timestamp).schema_copy
57
+ end
58
+
59
+ # An instance as the Hash the avro gem writes.
60
+ #
61
+ # @param struct [FieldStruct::Base] an instance of a struct class
62
+ # @param serialization [::Symbol, ::String]
63
+ # @param timestamp [::Symbol]
64
+ # @return [::Hash{::String=>::Object}]
65
+ # @raise [::ArgumentError] for a bad argument or a value that cannot be written exactly
66
+ def to_datum(struct, serialization: :avro, timestamp: :micros)
67
+ serialization = Check.call(struct.class, timestamp: timestamp, serialization: serialization)
68
+ DatumWriter.new(serialization, timestamp).struct(struct, Trail.root(struct.class))
69
+ end
70
+
71
+ # A struct built from a datum Hash.
72
+ #
73
+ # @param klass [::Class<FieldStruct::Base>] a +FieldStruct::Base+ subclass
74
+ # @param datum [::Hash{::String=>::Object}] the Hash the avro gem reads
75
+ # @param serialization [::Symbol, ::String]
76
+ # @return [FieldStruct::Base]
77
+ def from_datum(klass, datum, serialization: :avro)
78
+ serialization = Check.call(klass, serialization: serialization)
79
+ DatumReader.new(serialization).struct(klass, datum, Trail.root(klass))
80
+ end
81
+
82
+ # An instance as Avro binary (one datum, no header or container).
83
+ #
84
+ # @param struct [FieldStruct::Base]
85
+ # @param serialization [::Symbol, ::String]
86
+ # @param timestamp [::Symbol]
87
+ # @return [::String] binary bytes
88
+ def encode(struct, serialization: :avro, timestamp: :micros)
89
+ klass = struct.class
90
+ serialization = Check.call(klass, timestamp: timestamp, serialization: serialization)
91
+ entry = Cache.reader(klass, serialization, timestamp)
92
+ datum = DatumWriter.new(serialization, timestamp).struct(struct, Trail.root(klass))
93
+ write(entry.parsed, datum, struct)
94
+ end
95
+
96
+ # A struct read from Avro binary, written with the class's own schema or an older one.
97
+ #
98
+ # @param klass [::Class<FieldStruct::Base>] a named +FieldStruct::Base+ subclass
99
+ # @param bytes [::String]
100
+ # @param writer_schema [::Hash{::String=>::Object}, ::String, ::Object, nil] the schema older bytes were written with: a Hash,
101
+ # a JSON String or a parsed +Avro::Schema+
102
+ # @param serialization [::Symbol, ::String]
103
+ # @param timestamp [::Symbol]
104
+ # @return [FieldStruct::Base]
105
+ def decode(klass, bytes, writer_schema: nil, serialization: :avro, timestamp: :micros)
106
+ serialization = Check.call(klass, timestamp: timestamp, serialization: serialization, bytes: bytes)
107
+ entry = Cache.reader(klass, serialization, timestamp)
108
+ writer, reader = Evolution.schemas(entry, writer_schema)
109
+ datum = BytesReader.read(klass, bytes, writer, reader, writer_given: !writer_schema.nil?)
110
+ DatumReader.new(serialization).struct(klass, datum, Trail.root(klass))
111
+ end
112
+
113
+ # Forgets every cached schema, property list and checked writer schema. The cache keeps classes alive:
114
+ # under code reloading call this on each reload.
115
+ #
116
+ # @return [nil]
117
+ def clear_cache
118
+ Cache.clear
119
+ end
120
+
121
+ private
122
+
123
+ def write(parsed, datum, struct)
124
+ io = StringIO.new(''.b)
125
+ ::Avro::IO::DatumWriter.new(parsed).write(datum, ::Avro::IO::BinaryEncoder.new(io))
126
+ io.string
127
+ rescue ::Avro::IO::AvroTypeError
128
+ raise unless struct.respond_to?(:valid?) && !struct.valid?
129
+
130
+ raise ::ArgumentError, "FieldStruct::Avro can't encode an invalid #{struct.class}: #{struct.errors.full_messages.join('; ')}",
131
+ cause: nil
132
+ end
133
+ end
134
+ end
135
+ end
136
+
137
+ # The field option this adapter reads; registering it lets fields declare it (FS-B10a).
138
+ FieldStruct.register_option(:avro, type: Hash, owner: 'field_struct-avro')
@@ -0,0 +1,97 @@
1
+ # The field_struct namespace.
2
+ module FieldStruct
3
+ # Apache Avro for field_struct classes.
4
+ module Avro
5
+ TIMESTAMPS: ::Array[::Symbol]
6
+ VERSION: ::String
7
+
8
+ # The Avro record schema of a struct class.
9
+ #
10
+ # _@param_ `klass` — a named +FieldStruct::Base+ subclass
11
+ #
12
+ # _@param_ `serialization` — the +serialize+ format whose names become Avro field names
13
+ #
14
+ # _@param_ `timestamp` — +:micros+, +:nanos+ or +:millis+
15
+ #
16
+ # _@return_ — a fresh Hash
17
+ def self.schema: (singleton(FieldStruct::Base) klass, ?serialization: (::Symbol | ::String), ?timestamp: ::Symbol) -> ::Hash[::String, ::Object]
18
+
19
+ # An instance as the Hash the avro gem writes.
20
+ #
21
+ # _@param_ `struct` — an instance of a struct class
22
+ #
23
+ # _@param_ `serialization`
24
+ #
25
+ # _@param_ `timestamp`
26
+ def self.to_datum: (FieldStruct::Base struct, ?serialization: (::Symbol | ::String), ?timestamp: ::Symbol) -> ::Hash[::String, ::Object]
27
+
28
+ # A struct built from a datum Hash.
29
+ #
30
+ # _@param_ `klass` — a +FieldStruct::Base+ subclass
31
+ #
32
+ # _@param_ `datum` — the Hash the avro gem reads
33
+ #
34
+ # _@param_ `serialization`
35
+ def self.from_datum: (singleton(FieldStruct::Base) klass, ::Hash[::String, ::Object] datum, ?serialization: (::Symbol | ::String)) -> FieldStruct::Base
36
+
37
+ # An instance as Avro binary (one datum, no header or container).
38
+ #
39
+ # _@param_ `struct`
40
+ #
41
+ # _@param_ `serialization`
42
+ #
43
+ # _@param_ `timestamp`
44
+ #
45
+ # _@return_ — binary bytes
46
+ def self.encode: (FieldStruct::Base struct, ?serialization: (::Symbol | ::String), ?timestamp: ::Symbol) -> ::String
47
+
48
+ # A struct read from Avro binary, written with the class's own schema or an older one.
49
+ #
50
+ # _@param_ `klass` — a named +FieldStruct::Base+ subclass
51
+ #
52
+ # _@param_ `bytes`
53
+ #
54
+ # _@param_ `writer_schema` — the schema older bytes were written with: a Hash, a JSON String or a parsed +Avro::Schema+
55
+ #
56
+ # _@param_ `serialization`
57
+ #
58
+ # _@param_ `timestamp`
59
+ def self.decode: (
60
+ singleton(FieldStruct::Base) klass,
61
+ ::String bytes,
62
+ ?writer_schema: (::Hash[::String, ::Object] | ::String | ::Object)?,
63
+ ?serialization: (::Symbol | ::String),
64
+ ?timestamp: ::Symbol
65
+ ) -> FieldStruct::Base
66
+
67
+ # Forgets every cached schema, property list and checked writer schema. The cache keeps classes alive:
68
+ # under code reloading call this on each reload.
69
+ def self.clear_cache: () -> void
70
+
71
+ # Opt-in: +include FieldStruct::Avro::Methods+ in a struct adds +to_avro_schema+, +to_avro+ and +from_avro+.
72
+ module Methods
73
+ # _@param_ `base`
74
+ def self.included: (::Class base) -> void
75
+
76
+ # _@param_ `options` — the options of {FieldStruct::Avro.encode}
77
+ #
78
+ # _@return_ — Avro binary
79
+ def to_avro: (**::Object options) -> ::String
80
+
81
+ # The class-level methods +Methods+ adds.
82
+ module ClassMethods
83
+ # _@param_ `options` — the options of {FieldStruct::Avro.schema}
84
+ #
85
+ # _@return_ — see {FieldStruct::Avro.schema}
86
+ def to_avro_schema: (**::Object options) -> ::Hash[::String, ::Object]
87
+
88
+ # _@param_ `bytes` — Avro binary
89
+ #
90
+ # _@param_ `options` — the options of {FieldStruct::Avro.decode}
91
+ #
92
+ # _@return_ — an instance of the class
93
+ def from_avro: (::String bytes, **::Object options) -> FieldStruct::Base
94
+ end
95
+ end
96
+ end
97
+ end
metadata ADDED
@@ -0,0 +1,149 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: field_struct-avro
3
+ version: !ruby/object:Gem::Version
4
+ version: 1.0.0.pre1
5
+ platform: ruby
6
+ authors:
7
+ - Adrian Madrid
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: avro
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - "~>"
17
+ - !ruby/object:Gem::Version
18
+ version: '1.12'
19
+ type: :runtime
20
+ prerelease: false
21
+ version_requirements: !ruby/object:Gem::Requirement
22
+ requirements:
23
+ - - "~>"
24
+ - !ruby/object:Gem::Version
25
+ version: '1.12'
26
+ - !ruby/object:Gem::Dependency
27
+ name: bigdecimal
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - ">="
31
+ - !ruby/object:Gem::Version
32
+ version: '3.1'
33
+ type: :runtime
34
+ prerelease: false
35
+ version_requirements: !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - ">="
38
+ - !ruby/object:Gem::Version
39
+ version: '3.1'
40
+ - !ruby/object:Gem::Dependency
41
+ name: field_struct
42
+ requirement: !ruby/object:Gem::Requirement
43
+ requirements:
44
+ - - ">="
45
+ - !ruby/object:Gem::Version
46
+ version: 1.0.0.pre1
47
+ - - "<"
48
+ - !ruby/object:Gem::Version
49
+ version: '2'
50
+ type: :runtime
51
+ prerelease: false
52
+ version_requirements: !ruby/object:Gem::Requirement
53
+ requirements:
54
+ - - ">="
55
+ - !ruby/object:Gem::Version
56
+ version: 1.0.0.pre1
57
+ - - "<"
58
+ - !ruby/object:Gem::Version
59
+ version: '2'
60
+ - !ruby/object:Gem::Dependency
61
+ name: oj
62
+ requirement: !ruby/object:Gem::Requirement
63
+ requirements:
64
+ - - ">="
65
+ - !ruby/object:Gem::Version
66
+ version: 3.11.2
67
+ type: :runtime
68
+ prerelease: false
69
+ version_requirements: !ruby/object:Gem::Requirement
70
+ requirements:
71
+ - - ">="
72
+ - !ruby/object:Gem::Version
73
+ version: 3.11.2
74
+ - !ruby/object:Gem::Dependency
75
+ name: tzinfo
76
+ requirement: !ruby/object:Gem::Requirement
77
+ requirements:
78
+ - - "~>"
79
+ - !ruby/object:Gem::Version
80
+ version: '2.0'
81
+ type: :runtime
82
+ prerelease: false
83
+ version_requirements: !ruby/object:Gem::Requirement
84
+ requirements:
85
+ - - "~>"
86
+ - !ruby/object:Gem::Version
87
+ version: '2.0'
88
+ description: Generates an Avro record schema from a FieldStruct class, converts instances
89
+ to and from Avro datums, and reads and writes the Avro binary encoding, including
90
+ bytes written with an older schema.
91
+ email:
92
+ - adrian.madrid@timeworxs.com
93
+ executables: []
94
+ extensions: []
95
+ extra_rdoc_files: []
96
+ files:
97
+ - CHANGELOG.md
98
+ - LICENSE.txt
99
+ - README.md
100
+ - lib/field_struct/avro.rb
101
+ - lib/field_struct/avro/bytes_reader.rb
102
+ - lib/field_struct/avro/cache.rb
103
+ - lib/field_struct/avro/check.rb
104
+ - lib/field_struct/avro/datum_reader.rb
105
+ - lib/field_struct/avro/datum_writer.rb
106
+ - lib/field_struct/avro/defaults.rb
107
+ - lib/field_struct/avro/entry.rb
108
+ - lib/field_struct/avro/evolution.rb
109
+ - lib/field_struct/avro/methods.rb
110
+ - lib/field_struct/avro/names.rb
111
+ - lib/field_struct/avro/options.rb
112
+ - lib/field_struct/avro/projection.rb
113
+ - lib/field_struct/avro/resolution.rb
114
+ - lib/field_struct/avro/scalar_types.rb
115
+ - lib/field_struct/avro/schema_builder.rb
116
+ - lib/field_struct/avro/site.rb
117
+ - lib/field_struct/avro/stamp.rb
118
+ - lib/field_struct/avro/trail.rb
119
+ - lib/field_struct/avro/union_rules.rb
120
+ - lib/field_struct/avro/value_json.rb
121
+ - lib/field_struct/avro/version.rb
122
+ - lib/field_struct/avro/writer_schema.rb
123
+ - lib/field_struct/avro/zone.rb
124
+ - sig/field_struct-avro.rbs
125
+ homepage: https://github.com/gliders-rb/gems
126
+ licenses:
127
+ - MIT
128
+ metadata:
129
+ source_code_uri: https://github.com/gliders-rb/gems/tree/main/adapters/field_struct-avro
130
+ changelog_uri: https://github.com/gliders-rb/gems/blob/main/adapters/field_struct-avro/CHANGELOG.md
131
+ rubygems_mfa_required: 'true'
132
+ rdoc_options: []
133
+ require_paths:
134
+ - lib
135
+ required_ruby_version: !ruby/object:Gem::Requirement
136
+ requirements:
137
+ - - ">="
138
+ - !ruby/object:Gem::Version
139
+ version: '3.3'
140
+ required_rubygems_version: !ruby/object:Gem::Requirement
141
+ requirements:
142
+ - - ">="
143
+ - !ruby/object:Gem::Version
144
+ version: '0'
145
+ requirements: []
146
+ rubygems_version: 3.6.9
147
+ specification_version: 4
148
+ summary: Apache Avro schemas, datums and binary encoding for field_struct classes.
149
+ test_files: []