Class: Gapic::Schema::Api

Inherits:
Object
  • Object
show all
Defined in:
lib/gapic/schema/api.rb

Overview

A representation of a full API.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(request, parameter_schema: nil, error_output: $stderr, configuration: nil) ⇒ Api

Initializes an API object with the file descriptors that represent the API.

Parameters:



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/gapic/schema/api.rb', line 57

def initialize request, parameter_schema: nil, error_output: $stderr, configuration: nil
  @request = request
  loader = Loader.new
  @files = request.proto_file.map do |fd|
    loader.load_file fd, request.file_to_generate.include?(fd.name)
  end
  @files.each { |f| f.parent = self }
  @configuration = configuration
  @resource_types = analyze_resources
  @nonstandard_lro_services = analyze_nonstandard_lros

  parameter_schema ||= Gapic::Generators::DefaultGeneratorParameters.default_schema
  @protoc_parameters = parse_parameter request.parameter, parameter_schema, error_output
  @snippet_configs = loader.load_snippet_configs self.configuration[:snippet_configs_path]
  sanity_checks error_output
end

Instance Attribute Details

#enums ⇒ Array<Enum> (readonly)

Returns The top level enums seen across all files in this API.

Returns:

  • (Array<Enum>) —

    The top level enums seen across all files in this API.



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
 
# File 'lib/gapic/schema/api.rb', line 43

class Api
  attr_accessor :request
  attr_accessor :files
  attr_reader :snippet_configs

  # Initializes an API object with the file descriptors that represent the
  # API.
  #
  # @param request [Google::Protobuf::Compiler::CodeGeneratorRequest]
  #   The request object.
  # @param parameter_schema [Gapic::Schema::ParameterSchema]
  #   The request parameters schema to use
  # @param error_output [IO] An IO to write any errors/warnings to.
  # @param configuration [Hash] Optional override of configuration.
  def initialize request, parameter_schema: nil, error_output: $stderr, configuration: nil
    @request = request
    loader = Loader.new
    @files = request.proto_file.map do |fd|
      loader.load_file fd, request.file_to_generate.include?(fd.name)
    end
    @files.each { |f| f.parent = self }
    @configuration = configuration
    @resource_types = analyze_resources
    @nonstandard_lro_services = analyze_nonstandard_lros

    parameter_schema ||= Gapic::Generators::DefaultGeneratorParameters.default_schema
    @protoc_parameters = parse_parameter request.parameter, parameter_schema, error_output
    @snippet_configs = loader.load_snippet_configs self.configuration[:snippet_configs_path]
    sanity_checks error_output
  end

  def containing_api
    self
  end

  def containing_file
    nil
  end

  def lookup address
    address = address.join "." if address.is_a? Array
    @files.each do |f|
      lookup = f.lookup address
      return lookup if lookup
    end
    nil
  end

  def file_for address
    address = address.join "." if address.is_a? Array
    matching_files = @files.select { |f| f.lookup address }
    matching_files.first
  end

  def overrides_of key
    configuration&.dig(:overrides, key) || {}
  end

  def fix_file_path str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:file_path].nil?
    configuration[:overrides][:file_path].fetch str, str
  end

  def fix_namespace str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:namespace].nil?
    configuration[:overrides][:namespace].fetch str, str
  end

  def fix_service_name str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:service].nil?
    configuration[:overrides][:service].fetch str, str
  end

  # @return [Enumerable<Gapic::Schema::File>]
  def generate_files
    @files.select(&:generate?)
  end

  # @return [Enumerable<Gapic::Schema::Service>]
  def services
    @files.map(&:services).flatten
  end

  # @return [Enumerable<Gapic::Schema::Message>]
  def messages
    @files.map(&:messages).flatten
  end

  # Structured Hash representation of the parameter values.
  # @return [Hash]
  def protoc_options
    @protoc_options ||= begin
      result = {}
      @protoc_parameters.each do |parameter|
        result[str_to_key(parameter.config_name)] = parameter.config_value
      end
      result
    end
  end

  # Reconstructed string representation of the protoc parameters
  # @return [String]
  def protoc_parameter
    Gapic::Schema::RequestParamParser.reconstruct_parameters_string @protoc_parameters
  end

  # Structured representation of the samples configuration files.
  # @return [Array<Hash>]
  #   An array of the sample file hashes.
  def samples
    @samples ||= protoc_options["samples"].to_s.split(";").flat_map do |sample_path|
      YAML.load_file sample_path
    end.compact
  end

  # Structured representation of the standalone samples configuration files.
  # @return [Array<Hash>]
  #   An array of the standalone sample configuration hashes.
  def standalone_samples
    @standalone_samples ||= begin
      supported_types = [
        "com.google.api.codegen.SampleConfigProto",
        "com.google.api.codegen.samplegen.v1p2.SampleConfigProto"
      ]
      supported_sample_types = [nil, "standalone"]
      samples.select { |sample_file| supported_types.include? sample_file["type"] }
             .select { |sample_file| sample_file["schema_version"] == "1.2.0" }
             .map { |sample_file| sample_file["samples"] }
             .flatten.compact
             .select { |sample_config| supported_sample_types.include? sample_config["sample_type"] }
    end
  end

  # Structured representation of the standalone test samples configuration files.
  # @return [Array<Hash>]
  #   An array of the standalone sample configuration hashes.
  def standalone_test_samples
    @standalone_test_samples ||= begin
      test_samples = samples.select { |sample| sample["type"] == "test/samples" }
      test_samples.select { |sample| sample["schema_version"] == "1" || sample["schema_version"] == 1 }
                  .map { |sample| sample["samples"] }
                  .flatten.compact
    end
  end

  # Structured representation of the inline samples configuration files.
  # @return [Array<Hash>]
  #   An array of the incode sample configuration hashes, sorted by sample_type.
  def incode_samples
    @incode_samples ||= begin
      supported_types = [
        "com.google.api.codegen.SampleConfigProto",
        "com.google.api.codegen.samplegen.v1p2.SampleConfigProto"
      ]
      samples.select { |sample_file| supported_types.include? sample_file["type"] }
             .select { |sample_file| sample_file["schema_version"] == "1.2.0" }
             .map { |sample_file| sample_file["samples"] }
             .flatten.compact
             .select { |sample_config| sample_config["sample_type"]&.start_with? "incode/" }
             .sort_by { |sample_config| sample_config["sample_type"] }
    end
  end

  # Return all snippet configs for the given method address. Returns the
  # empty array if there are no snippet configs.
  # @param address [String] Method address in the form
  #   `proto.package.v1.ServiceName.MethodName`
  # @return [Array<
  #   Google::Cloud::Tools::SnippetGen::ConfigLanguage::V1::SnippetConfig>]
  def snippet_configs_for address
    address = address.join "." if address.is_a? ::Array
    @snippet_configs.find_all do |config|
      rpc = config.rpc
      rpc.api_version.any? do |vers|
        address == "#{rpc.proto_package}.#{vers}.#{rpc.service_name}.#{rpc.rpc_name}"
      end
    end
  end

  # Structured Hash representation of the configuration file.
  # @return [Hash]
  #   A Hash of the configuration values.
  def configuration
    @configuration ||= begin
      config_file = protoc_options["configuration"]
      config = config_file ? YAML.load_file(config_file) : {}
      protoc_options.each do |k, v|
        next if k == "configuration"
        branch = parse_key(key_to_str(k)).reverse.inject(v) { |m, s| { str_to_key(s) => m } }
        config = deep_merge config, branch
      end
      config
    end
  end

  # Whether the generate_path_helpers_output parameter was given in the configuration
  def generate_path_helpers_output_defined?
    configuration.key? :generate_path_helpers_output
  end

  # Sets the generate_path_helpers_output parameter in the configuration
  def generate_path_helpers_output= value
    configuration[:generate_path_helpers_output] = value
  end

  # Whether to generate path helpers for output as well as input messages
  def generate_path_helpers_output?
    # if not set in configuration, false by default
    configuration[:generate_path_helpers_output] ||= false
  end

  # Whether to generate REST clients
  def generate_rest_clients?
    return false if configuration[:transports].nil?
    configuration[:transports].include? "rest"
  end

  # Whether to generate GRPC clients
  def generate_grpc_clients?
    return true if configuration[:transports].nil?
    configuration[:transports].include? "grpc"
  end

  ##
  # The default transport, used when choosing which client class a docs
  # xref should link to.
  #
  # @return [:grpc,:rest]
  #
  def default_transport
    generate_grpc_clients? ? :grpc : :rest
  end

  # Whether to generate standalone snippets
  def generate_standalone_snippets?
    configuration.fetch :generate_standalone_snippets, true
  end

  # Whether to generate inline documentation snippets
  def generate_yardoc_snippets?
    configuration.fetch :generate_yardoc_snippets, true
  end

  # Whether to generate gapic metadata (drift manifest) file
  # @return [Boolean]
  def generate_metadata
    configuration[:generate_metadata] ||= false
  end

  # Whether the override_proto_namespaces parameter was given in the configuration
  def override_proto_namespaces_defined?
    configuration.key? :override_proto_namespaces
  end

  # Sets the override_proto_namespaces parameter in the configuration
  def override_proto_namespaces= value
    configuration[:override_proto_namespaces] = value
  end

  # Whether namespace overrides apply to proto/grpc class references
  def override_proto_namespaces?
    configuration[:override_proto_namespaces] ||= false
  end

  # Raw parsed json of the combined grpc service config files if provided
  # or an empty hash if no config was provided
  def grpc_service_config_raw
    @grpc_service_config_raw ||= begin
      filenames = protoc_options["grpc_service_config"].to_s.split ";"
      filenames.inject({}) do |running_hash, filename|
        file_hash = JSON.parse ::File.read filename
        deep_merge running_hash, file_hash
      end
    end
  end

  # Parsed grpc service config
  def grpc_service_config
    @grpc_service_config ||= Gapic::GrpcServiceConfig::Parser.parse grpc_service_config_raw
  end

  # Raw text of the service.yaml if given as a parameter
  # or nil if no parameter given
  # @return [String]
  def service_config_raw
    @service_config_raw ||= begin
      filename = protoc_options[:service_yaml]
      ::File.read filename if filename
    end
  end

  # Parsed service config
  # @return [Google::Api::Service]
  def service_config
    @service_config ||= Gapic::Schema::ServiceConfigParser.parse_service_yaml service_config_raw
  end

  # Parsed API Metadata model
  # @return [Gapic::Model::ApiMetadata]
  def api_metadata
    @api_metadata ||= begin
      api_metadata = Gapic::Model::ApiMetadata.new
      Gapic::Schema::ServiceConfigParser.parse_api_metadata service_config_raw, api_metadata
      api_metadata.standardize_names!
      api_metadata.standardize_title! gem_name: configuration.fetch(:gem, nil)&.fetch(:name, "")
      api_metadata.standardize_descriptions!
      api_metadata.standardize_auto_populated_fields! @service_config
      api_metadata
    end
  end

  # Get a resource given its type string
  def lookup_resource_type resource_type
    @resource_types[resource_type]
  end

  # Given a service, find all common services that use it as a delegate.
  def common_services_for delegate
    @delegate_to_common ||= (configuration[:common_services] || {}).each_with_object({}) do |(c, d), mapping|
      (mapping[d] ||= []) << c
    end
    all_services = services
    @delegate_to_common.fetch(delegate.address.join("."), []).map do |addr|
      addr = addr.split "."
      all_services.find { |s| s.address == addr }
    end.compact.uniq
  end

  # Given a common service, return its delegate.
  def delegate_service_for common
    addr = (configuration[:common_services] || {})[common.address.join "."]
    return nil unless addr
    addr = addr.split "."
    services.find { |s| s.address == addr }
  end

  ##
  # Returns a model for the nonstandard LRO for a given service
  # The `analyze_nonstandard_lros` method fills in the model cache
  #
  # @param service_full_name [String]
  #
  # @return [Gapic::Model::Service::NonstandardLroProvider, Gapic::Model::Service::NoNonstandardLro]
  def nonstandard_lro_model_for service_full_name
    if @nonstandard_lro_services.key? service_full_name
      @nonstandard_lro_services[service_full_name]
    else
      Gapic::Model::Service::NoNonstandardLro.instance
    end
  end

  ##
  # Whether configuration has an override for the wrapper gem name
  # @return [Boolean]
  def wrapper_gem_name_override?
    configuration.key?(:overrides) &&
      configuration[:overrides].key?(:wrapper_gem_name)
  end

  ##
  # An override for the wrapper gem name in the configuration
  # @return [String, nil]
  def wrapper_gem_name_override
    return nil unless wrapper_gem_name_override?
    return nil if configuration[:overrides][:wrapper_gem_name].nil?

    wrapper_name_config = configuration[:overrides][:wrapper_gem_name].strip
    return nil if wrapper_name_config.empty?

    wrapper_name_config
  end

  private

  # Perform a variety of sanity checks on the data, and prints errors to
  # the given output as appropriate.
  #
  # @param output [IO] Stream to write outputs to.
  def sanity_checks output
    addrs = services.map { |service| service.address.join "." }
    configuration[:common_services]&.each do |k, v|
      output.puts "WARNING: configured common service #{k} is not present" unless addrs.include? k
      output.puts "WARNING: configured common service delegate #{v} is not present" unless addrs.include? v
    end
    # TODO: Sanity check snippet configs to ensure that the type of call
    # (e.g. streaming, lro, etc) matches the rpc type. Warn and remove any
    # noncomplying snippet configs to prevent crashes when rendering.
  end

  # Does a pre-analysis of all resources defined in the job. This has
  # two effects:
  # * Side effect: each resource has its parent_resources field set.
  # * A mapping from resource type to resource wrapper is returned.
  def analyze_resources
    # In order to set parent_resources, we first populate a mapping from
    # parsed pattern to resources that use it (in the patterns variable).
    # Note that there may be multiple resources associated with a pattern.
    # (This is uncommon, but one example is monitoring v3 which uses
    # "projects/*" for its workspace type as well as inheriting the common
    # project type. We thus map each pattern to an array of resources.)
    # Constructing the patterns mapping is done in one pass along with
    # populating the type mapping (which maps only to single resources.)
    # Then, we go through all resources again, get each's expected parent
    # patterns, and anything that shows up in the patterns mapping is taken
    # to be a parent.
    types = {}
    patterns = {}
    @files.each do |file|
      file.resources.each { |resource| populate_resource_lookups resource, types, patterns }
      file.messages.each { |message| populate_message_resource_lookups message, types, patterns }
    end
    types.each_value do |resource|
      parents = resource.parsed_parent_patterns
                        .flat_map { |pat| Array(patterns[pat]) }
                        .uniq
      resource.parent_resources.replace parents
    end
    types
  end

  def populate_resource_lookups resource, types, patterns
    types[resource.type] = resource
    resource.parsed_patterns.each do |pat|
      ((patterns[pat] ||= []) << resource).uniq!
    end
  end

  def populate_message_resource_lookups message, types, patterns
    populate_resource_lookups message.resource, types, patterns if message.resource
    message.nested_messages.each do |nested|
      populate_message_resource_lookups nested, types, patterns
    end
  end

  ##
  # Does a pre-analysis of the nonstandard LRO for every service.
  # For the services that provide nonstandard LRO functionality, cashes a model for the future use
  #
  # @return [Hash<String, Gapic::Model::Service::NonstandardLroProvider>]
  def analyze_nonstandard_lros
    service_registry = {}

    @files.each do |file|
      file.services.each do |service|
        nonstandard_lro = Gapic::Model::Service.parse_nonstandard_lro service
        service_registry[service.full_name] = nonstandard_lro if nonstandard_lro
      end
    end

    service_registry
  end

  # Parse a comma-delimited list of equals-delimited lists of strings, while
  # mapping backslash-escaped commas and equal signs to literal characters.
  # @param str [String]
  # @param error_output [IO] Stream to write outputs to.
  # @return [Array<Gapic::Schema::RequestParameter>]
  def parse_parameter str, parameter_schema, error_output
    Gapic::Schema::RequestParamParser.parse_parameters_string str,
                                                              param_schema: parameter_schema,
                                                              error_output: error_output
  end

  # split the string on periods, but map backslash-escaped periods to
  # literal periods.
  def parse_key str
    str.scan(/\.|\\.|[^.\\]+/)
       .each_with_object([String.new]) do |tok, arr|
         if tok == "."
           arr.append String.new
         elsif tok.start_with? "\\"
           arr.last << tok[1]
         else
           arr.last << tok
         end
         arr
       end
  end

  def str_to_key str
    str = str.to_s
    str.start_with?(":") ? str[1..].to_sym : str
  end

  def key_to_str key
    key.is_a?(::Symbol) ? ":#{key}" : key.to_s
  end

  def deep_merge left, right
    left.merge right do |_k, lt, rt|
      if lt.is_a?(Hash) && rt.is_a?(Hash)
        deep_merge lt, rt
      elsif lt.is_a?(Array) && rt.is_a?(Array)
        lt + rt
      else
        rt
      end
    end
  end
end

#files ⇒ Array<File>

Returns The files represented by this API.

Returns:

  • (Array<File>) —

    The files represented by this API.



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
 
# File 'lib/gapic/schema/api.rb', line 43

class Api
  attr_accessor :request
  attr_accessor :files
  attr_reader :snippet_configs

  # Initializes an API object with the file descriptors that represent the
  # API.
  #
  # @param request [Google::Protobuf::Compiler::CodeGeneratorRequest]
  #   The request object.
  # @param parameter_schema [Gapic::Schema::ParameterSchema]
  #   The request parameters schema to use
  # @param error_output [IO] An IO to write any errors/warnings to.
  # @param configuration [Hash] Optional override of configuration.
  def initialize request, parameter_schema: nil, error_output: $stderr, configuration: nil
    @request = request
    loader = Loader.new
    @files = request.proto_file.map do |fd|
      loader.load_file fd, request.file_to_generate.include?(fd.name)
    end
    @files.each { |f| f.parent = self }
    @configuration = configuration
    @resource_types = analyze_resources
    @nonstandard_lro_services = analyze_nonstandard_lros

    parameter_schema ||= Gapic::Generators::DefaultGeneratorParameters.default_schema
    @protoc_parameters = parse_parameter request.parameter, parameter_schema, error_output
    @snippet_configs = loader.load_snippet_configs self.configuration[:snippet_configs_path]
    sanity_checks error_output
  end

  def containing_api
    self
  end

  def containing_file
    nil
  end

  def lookup address
    address = address.join "." if address.is_a? Array
    @files.each do |f|
      lookup = f.lookup address
      return lookup if lookup
    end
    nil
  end

  def file_for address
    address = address.join "." if address.is_a? Array
    matching_files = @files.select { |f| f.lookup address }
    matching_files.first
  end

  def overrides_of key
    configuration&.dig(:overrides, key) || {}
  end

  def fix_file_path str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:file_path].nil?
    configuration[:overrides][:file_path].fetch str, str
  end

  def fix_namespace str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:namespace].nil?
    configuration[:overrides][:namespace].fetch str, str
  end

  def fix_service_name str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:service].nil?
    configuration[:overrides][:service].fetch str, str
  end

  # @return [Enumerable<Gapic::Schema::File>]
  def generate_files
    @files.select(&:generate?)
  end

  # @return [Enumerable<Gapic::Schema::Service>]
  def services
    @files.map(&:services).flatten
  end

  # @return [Enumerable<Gapic::Schema::Message>]
  def messages
    @files.map(&:messages).flatten
  end

  # Structured Hash representation of the parameter values.
  # @return [Hash]
  def protoc_options
    @protoc_options ||= begin
      result = {}
      @protoc_parameters.each do |parameter|
        result[str_to_key(parameter.config_name)] = parameter.config_value
      end
      result
    end
  end

  # Reconstructed string representation of the protoc parameters
  # @return [String]
  def protoc_parameter
    Gapic::Schema::RequestParamParser.reconstruct_parameters_string @protoc_parameters
  end

  # Structured representation of the samples configuration files.
  # @return [Array<Hash>]
  #   An array of the sample file hashes.
  def samples
    @samples ||= protoc_options["samples"].to_s.split(";").flat_map do |sample_path|
      YAML.load_file sample_path
    end.compact
  end

  # Structured representation of the standalone samples configuration files.
  # @return [Array<Hash>]
  #   An array of the standalone sample configuration hashes.
  def standalone_samples
    @standalone_samples ||= begin
      supported_types = [
        "com.google.api.codegen.SampleConfigProto",
        "com.google.api.codegen.samplegen.v1p2.SampleConfigProto"
      ]
      supported_sample_types = [nil, "standalone"]
      samples.select { |sample_file| supported_types.include? sample_file["type"] }
             .select { |sample_file| sample_file["schema_version"] == "1.2.0" }
             .map { |sample_file| sample_file["samples"] }
             .flatten.compact
             .select { |sample_config| supported_sample_types.include? sample_config["sample_type"] }
    end
  end

  # Structured representation of the standalone test samples configuration files.
  # @return [Array<Hash>]
  #   An array of the standalone sample configuration hashes.
  def standalone_test_samples
    @standalone_test_samples ||= begin
      test_samples = samples.select { |sample| sample["type"] == "test/samples" }
      test_samples.select { |sample| sample["schema_version"] == "1" || sample["schema_version"] == 1 }
                  .map { |sample| sample["samples"] }
                  .flatten.compact
    end
  end

  # Structured representation of the inline samples configuration files.
  # @return [Array<Hash>]
  #   An array of the incode sample configuration hashes, sorted by sample_type.
  def incode_samples
    @incode_samples ||= begin
      supported_types = [
        "com.google.api.codegen.SampleConfigProto",
        "com.google.api.codegen.samplegen.v1p2.SampleConfigProto"
      ]
      samples.select { |sample_file| supported_types.include? sample_file["type"] }
             .select { |sample_file| sample_file["schema_version"] == "1.2.0" }
             .map { |sample_file| sample_file["samples"] }
             .flatten.compact
             .select { |sample_config| sample_config["sample_type"]&.start_with? "incode/" }
             .sort_by { |sample_config| sample_config["sample_type"] }
    end
  end

  # Return all snippet configs for the given method address. Returns the
  # empty array if there are no snippet configs.
  # @param address [String] Method address in the form
  #   `proto.package.v1.ServiceName.MethodName`
  # @return [Array<
  #   Google::Cloud::Tools::SnippetGen::ConfigLanguage::V1::SnippetConfig>]
  def snippet_configs_for address
    address = address.join "." if address.is_a? ::Array
    @snippet_configs.find_all do |config|
      rpc = config.rpc
      rpc.api_version.any? do |vers|
        address == "#{rpc.proto_package}.#{vers}.#{rpc.service_name}.#{rpc.rpc_name}"
      end
    end
  end

  # Structured Hash representation of the configuration file.
  # @return [Hash]
  #   A Hash of the configuration values.
  def configuration
    @configuration ||= begin
      config_file = protoc_options["configuration"]
      config = config_file ? YAML.load_file(config_file) : {}
      protoc_options.each do |k, v|
        next if k == "configuration"
        branch = parse_key(key_to_str(k)).reverse.inject(v) { |m, s| { str_to_key(s) => m } }
        config = deep_merge config, branch
      end
      config
    end
  end

  # Whether the generate_path_helpers_output parameter was given in the configuration
  def generate_path_helpers_output_defined?
    configuration.key? :generate_path_helpers_output
  end

  # Sets the generate_path_helpers_output parameter in the configuration
  def generate_path_helpers_output= value
    configuration[:generate_path_helpers_output] = value
  end

  # Whether to generate path helpers for output as well as input messages
  def generate_path_helpers_output?
    # if not set in configuration, false by default
    configuration[:generate_path_helpers_output] ||= false
  end

  # Whether to generate REST clients
  def generate_rest_clients?
    return false if configuration[:transports].nil?
    configuration[:transports].include? "rest"
  end

  # Whether to generate GRPC clients
  def generate_grpc_clients?
    return true if configuration[:transports].nil?
    configuration[:transports].include? "grpc"
  end

  ##
  # The default transport, used when choosing which client class a docs
  # xref should link to.
  #
  # @return [:grpc,:rest]
  #
  def default_transport
    generate_grpc_clients? ? :grpc : :rest
  end

  # Whether to generate standalone snippets
  def generate_standalone_snippets?
    configuration.fetch :generate_standalone_snippets, true
  end

  # Whether to generate inline documentation snippets
  def generate_yardoc_snippets?
    configuration.fetch :generate_yardoc_snippets, true
  end

  # Whether to generate gapic metadata (drift manifest) file
  # @return [Boolean]
  def generate_metadata
    configuration[:generate_metadata] ||= false
  end

  # Whether the override_proto_namespaces parameter was given in the configuration
  def override_proto_namespaces_defined?
    configuration.key? :override_proto_namespaces
  end

  # Sets the override_proto_namespaces parameter in the configuration
  def override_proto_namespaces= value
    configuration[:override_proto_namespaces] = value
  end

  # Whether namespace overrides apply to proto/grpc class references
  def override_proto_namespaces?
    configuration[:override_proto_namespaces] ||= false
  end

  # Raw parsed json of the combined grpc service config files if provided
  # or an empty hash if no config was provided
  def grpc_service_config_raw
    @grpc_service_config_raw ||= begin
      filenames = protoc_options["grpc_service_config"].to_s.split ";"
      filenames.inject({}) do |running_hash, filename|
        file_hash = JSON.parse ::File.read filename
        deep_merge running_hash, file_hash
      end
    end
  end

  # Parsed grpc service config
  def grpc_service_config
    @grpc_service_config ||= Gapic::GrpcServiceConfig::Parser.parse grpc_service_config_raw
  end

  # Raw text of the service.yaml if given as a parameter
  # or nil if no parameter given
  # @return [String]
  def service_config_raw
    @service_config_raw ||= begin
      filename = protoc_options[:service_yaml]
      ::File.read filename if filename
    end
  end

  # Parsed service config
  # @return [Google::Api::Service]
  def service_config
    @service_config ||= Gapic::Schema::ServiceConfigParser.parse_service_yaml service_config_raw
  end

  # Parsed API Metadata model
  # @return [Gapic::Model::ApiMetadata]
  def api_metadata
    @api_metadata ||= begin
      api_metadata = Gapic::Model::ApiMetadata.new
      Gapic::Schema::ServiceConfigParser.parse_api_metadata service_config_raw, api_metadata
      api_metadata.standardize_names!
      api_metadata.standardize_title! gem_name: configuration.fetch(:gem, nil)&.fetch(:name, "")
      api_metadata.standardize_descriptions!
      api_metadata.standardize_auto_populated_fields! @service_config
      api_metadata
    end
  end

  # Get a resource given its type string
  def lookup_resource_type resource_type
    @resource_types[resource_type]
  end

  # Given a service, find all common services that use it as a delegate.
  def common_services_for delegate
    @delegate_to_common ||= (configuration[:common_services] || {}).each_with_object({}) do |(c, d), mapping|
      (mapping[d] ||= []) << c
    end
    all_services = services
    @delegate_to_common.fetch(delegate.address.join("."), []).map do |addr|
      addr = addr.split "."
      all_services.find { |s| s.address == addr }
    end.compact.uniq
  end

  # Given a common service, return its delegate.
  def delegate_service_for common
    addr = (configuration[:common_services] || {})[common.address.join "."]
    return nil unless addr
    addr = addr.split "."
    services.find { |s| s.address == addr }
  end

  ##
  # Returns a model for the nonstandard LRO for a given service
  # The `analyze_nonstandard_lros` method fills in the model cache
  #
  # @param service_full_name [String]
  #
  # @return [Gapic::Model::Service::NonstandardLroProvider, Gapic::Model::Service::NoNonstandardLro]
  def nonstandard_lro_model_for service_full_name
    if @nonstandard_lro_services.key? service_full_name
      @nonstandard_lro_services[service_full_name]
    else
      Gapic::Model::Service::NoNonstandardLro.instance
    end
  end

  ##
  # Whether configuration has an override for the wrapper gem name
  # @return [Boolean]
  def wrapper_gem_name_override?
    configuration.key?(:overrides) &&
      configuration[:overrides].key?(:wrapper_gem_name)
  end

  ##
  # An override for the wrapper gem name in the configuration
  # @return [String, nil]
  def wrapper_gem_name_override
    return nil unless wrapper_gem_name_override?
    return nil if configuration[:overrides][:wrapper_gem_name].nil?

    wrapper_name_config = configuration[:overrides][:wrapper_gem_name].strip
    return nil if wrapper_name_config.empty?

    wrapper_name_config
  end

  private

  # Perform a variety of sanity checks on the data, and prints errors to
  # the given output as appropriate.
  #
  # @param output [IO] Stream to write outputs to.
  def sanity_checks output
    addrs = services.map { |service| service.address.join "." }
    configuration[:common_services]&.each do |k, v|
      output.puts "WARNING: configured common service #{k} is not present" unless addrs.include? k
      output.puts "WARNING: configured common service delegate #{v} is not present" unless addrs.include? v
    end
    # TODO: Sanity check snippet configs to ensure that the type of call
    # (e.g. streaming, lro, etc) matches the rpc type. Warn and remove any
    # noncomplying snippet configs to prevent crashes when rendering.
  end

  # Does a pre-analysis of all resources defined in the job. This has
  # two effects:
  # * Side effect: each resource has its parent_resources field set.
  # * A mapping from resource type to resource wrapper is returned.
  def analyze_resources
    # In order to set parent_resources, we first populate a mapping from
    # parsed pattern to resources that use it (in the patterns variable).
    # Note that there may be multiple resources associated with a pattern.
    # (This is uncommon, but one example is monitoring v3 which uses
    # "projects/*" for its workspace type as well as inheriting the common
    # project type. We thus map each pattern to an array of resources.)
    # Constructing the patterns mapping is done in one pass along with
    # populating the type mapping (which maps only to single resources.)
    # Then, we go through all resources again, get each's expected parent
    # patterns, and anything that shows up in the patterns mapping is taken
    # to be a parent.
    types = {}
    patterns = {}
    @files.each do |file|
      file.resources.each { |resource| populate_resource_lookups resource, types, patterns }
      file.messages.each { |message| populate_message_resource_lookups message, types, patterns }
    end
    types.each_value do |resource|
      parents = resource.parsed_parent_patterns
                        .flat_map { |pat| Array(patterns[pat]) }
                        .uniq
      resource.parent_resources.replace parents
    end
    types
  end

  def populate_resource_lookups resource, types, patterns
    types[resource.type] = resource
    resource.parsed_patterns.each do |pat|
      ((patterns[pat] ||= []) << resource).uniq!
    end
  end

  def populate_message_resource_lookups message, types, patterns
    populate_resource_lookups message.resource, types, patterns if message.resource
    message.nested_messages.each do |nested|
      populate_message_resource_lookups nested, types, patterns
    end
  end

  ##
  # Does a pre-analysis of the nonstandard LRO for every service.
  # For the services that provide nonstandard LRO functionality, cashes a model for the future use
  #
  # @return [Hash<String, Gapic::Model::Service::NonstandardLroProvider>]
  def analyze_nonstandard_lros
    service_registry = {}

    @files.each do |file|
      file.services.each do |service|
        nonstandard_lro = Gapic::Model::Service.parse_nonstandard_lro service
        service_registry[service.full_name] = nonstandard_lro if nonstandard_lro
      end
    end

    service_registry
  end

  # Parse a comma-delimited list of equals-delimited lists of strings, while
  # mapping backslash-escaped commas and equal signs to literal characters.
  # @param str [String]
  # @param error_output [IO] Stream to write outputs to.
  # @return [Array<Gapic::Schema::RequestParameter>]
  def parse_parameter str, parameter_schema, error_output
    Gapic::Schema::RequestParamParser.parse_parameters_string str,
                                                              param_schema: parameter_schema,
                                                              error_output: error_output
  end

  # split the string on periods, but map backslash-escaped periods to
  # literal periods.
  def parse_key str
    str.scan(/\.|\\.|[^.\\]+/)
       .each_with_object([String.new]) do |tok, arr|
         if tok == "."
           arr.append String.new
         elsif tok.start_with? "\\"
           arr.last << tok[1]
         else
           arr.last << tok
         end
         arr
       end
  end

  def str_to_key str
    str = str.to_s
    str.start_with?(":") ? str[1..].to_sym : str
  end

  def key_to_str key
    key.is_a?(::Symbol) ? ":#{key}" : key.to_s
  end

  def deep_merge left, right
    left.merge right do |_k, lt, rt|
      if lt.is_a?(Hash) && rt.is_a?(Hash)
        deep_merge lt, rt
      elsif lt.is_a?(Array) && rt.is_a?(Array)
        lt + rt
      else
        rt
      end
    end
  end
end

#messages ⇒ Enumerable<Gapic::Schema::Message> (readonly)

Returns:



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
 
# File 'lib/gapic/schema/api.rb', line 43

class Api
  attr_accessor :request
  attr_accessor :files
  attr_reader :snippet_configs

  # Initializes an API object with the file descriptors that represent the
  # API.
  #
  # @param request [Google::Protobuf::Compiler::CodeGeneratorRequest]
  #   The request object.
  # @param parameter_schema [Gapic::Schema::ParameterSchema]
  #   The request parameters schema to use
  # @param error_output [IO] An IO to write any errors/warnings to.
  # @param configuration [Hash] Optional override of configuration.
  def initialize request, parameter_schema: nil, error_output: $stderr, configuration: nil
    @request = request
    loader = Loader.new
    @files = request.proto_file.map do |fd|
      loader.load_file fd, request.file_to_generate.include?(fd.name)
    end
    @files.each { |f| f.parent = self }
    @configuration = configuration
    @resource_types = analyze_resources
    @nonstandard_lro_services = analyze_nonstandard_lros

    parameter_schema ||= Gapic::Generators::DefaultGeneratorParameters.default_schema
    @protoc_parameters = parse_parameter request.parameter, parameter_schema, error_output
    @snippet_configs = loader.load_snippet_configs self.configuration[:snippet_configs_path]
    sanity_checks error_output
  end

  def containing_api
    self
  end

  def containing_file
    nil
  end

  def lookup address
    address = address.join "." if address.is_a? Array
    @files.each do |f|
      lookup = f.lookup address
      return lookup if lookup
    end
    nil
  end

  def file_for address
    address = address.join "." if address.is_a? Array
    matching_files = @files.select { |f| f.lookup address }
    matching_files.first
  end

  def overrides_of key
    configuration&.dig(:overrides, key) || {}
  end

  def fix_file_path str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:file_path].nil?
    configuration[:overrides][:file_path].fetch str, str
  end

  def fix_namespace str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:namespace].nil?
    configuration[:overrides][:namespace].fetch str, str
  end

  def fix_service_name str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:service].nil?
    configuration[:overrides][:service].fetch str, str
  end

  # @return [Enumerable<Gapic::Schema::File>]
  def generate_files
    @files.select(&:generate?)
  end

  # @return [Enumerable<Gapic::Schema::Service>]
  def services
    @files.map(&:services).flatten
  end

  # @return [Enumerable<Gapic::Schema::Message>]
  def messages
    @files.map(&:messages).flatten
  end

  # Structured Hash representation of the parameter values.
  # @return [Hash]
  def protoc_options
    @protoc_options ||= begin
      result = {}
      @protoc_parameters.each do |parameter|
        result[str_to_key(parameter.config_name)] = parameter.config_value
      end
      result
    end
  end

  # Reconstructed string representation of the protoc parameters
  # @return [String]
  def protoc_parameter
    Gapic::Schema::RequestParamParser.reconstruct_parameters_string @protoc_parameters
  end

  # Structured representation of the samples configuration files.
  # @return [Array<Hash>]
  #   An array of the sample file hashes.
  def samples
    @samples ||= protoc_options["samples"].to_s.split(";").flat_map do |sample_path|
      YAML.load_file sample_path
    end.compact
  end

  # Structured representation of the standalone samples configuration files.
  # @return [Array<Hash>]
  #   An array of the standalone sample configuration hashes.
  def standalone_samples
    @standalone_samples ||= begin
      supported_types = [
        "com.google.api.codegen.SampleConfigProto",
        "com.google.api.codegen.samplegen.v1p2.SampleConfigProto"
      ]
      supported_sample_types = [nil, "standalone"]
      samples.select { |sample_file| supported_types.include? sample_file["type"] }
             .select { |sample_file| sample_file["schema_version"] == "1.2.0" }
             .map { |sample_file| sample_file["samples"] }
             .flatten.compact
             .select { |sample_config| supported_sample_types.include? sample_config["sample_type"] }
    end
  end

  # Structured representation of the standalone test samples configuration files.
  # @return [Array<Hash>]
  #   An array of the standalone sample configuration hashes.
  def standalone_test_samples
    @standalone_test_samples ||= begin
      test_samples = samples.select { |sample| sample["type"] == "test/samples" }
      test_samples.select { |sample| sample["schema_version"] == "1" || sample["schema_version"] == 1 }
                  .map { |sample| sample["samples"] }
                  .flatten.compact
    end
  end

  # Structured representation of the inline samples configuration files.
  # @return [Array<Hash>]
  #   An array of the incode sample configuration hashes, sorted by sample_type.
  def incode_samples
    @incode_samples ||= begin
      supported_types = [
        "com.google.api.codegen.SampleConfigProto",
        "com.google.api.codegen.samplegen.v1p2.SampleConfigProto"
      ]
      samples.select { |sample_file| supported_types.include? sample_file["type"] }
             .select { |sample_file| sample_file["schema_version"] == "1.2.0" }
             .map { |sample_file| sample_file["samples"] }
             .flatten.compact
             .select { |sample_config| sample_config["sample_type"]&.start_with? "incode/" }
             .sort_by { |sample_config| sample_config["sample_type"] }
    end
  end

  # Return all snippet configs for the given method address. Returns the
  # empty array if there are no snippet configs.
  # @param address [String] Method address in the form
  #   `proto.package.v1.ServiceName.MethodName`
  # @return [Array<
  #   Google::Cloud::Tools::SnippetGen::ConfigLanguage::V1::SnippetConfig>]
  def snippet_configs_for address
    address = address.join "." if address.is_a? ::Array
    @snippet_configs.find_all do |config|
      rpc = config.rpc
      rpc.api_version.any? do |vers|
        address == "#{rpc.proto_package}.#{vers}.#{rpc.service_name}.#{rpc.rpc_name}"
      end
    end
  end

  # Structured Hash representation of the configuration file.
  # @return [Hash]
  #   A Hash of the configuration values.
  def configuration
    @configuration ||= begin
      config_file = protoc_options["configuration"]
      config = config_file ? YAML.load_file(config_file) : {}
      protoc_options.each do |k, v|
        next if k == "configuration"
        branch = parse_key(key_to_str(k)).reverse.inject(v) { |m, s| { str_to_key(s) => m } }
        config = deep_merge config, branch
      end
      config
    end
  end

  # Whether the generate_path_helpers_output parameter was given in the configuration
  def generate_path_helpers_output_defined?
    configuration.key? :generate_path_helpers_output
  end

  # Sets the generate_path_helpers_output parameter in the configuration
  def generate_path_helpers_output= value
    configuration[:generate_path_helpers_output] = value
  end

  # Whether to generate path helpers for output as well as input messages
  def generate_path_helpers_output?
    # if not set in configuration, false by default
    configuration[:generate_path_helpers_output] ||= false
  end

  # Whether to generate REST clients
  def generate_rest_clients?
    return false if configuration[:transports].nil?
    configuration[:transports].include? "rest"
  end

  # Whether to generate GRPC clients
  def generate_grpc_clients?
    return true if configuration[:transports].nil?
    configuration[:transports].include? "grpc"
  end

  ##
  # The default transport, used when choosing which client class a docs
  # xref should link to.
  #
  # @return [:grpc,:rest]
  #
  def default_transport
    generate_grpc_clients? ? :grpc : :rest
  end

  # Whether to generate standalone snippets
  def generate_standalone_snippets?
    configuration.fetch :generate_standalone_snippets, true
  end

  # Whether to generate inline documentation snippets
  def generate_yardoc_snippets?
    configuration.fetch :generate_yardoc_snippets, true
  end

  # Whether to generate gapic metadata (drift manifest) file
  # @return [Boolean]
  def generate_metadata
    configuration[:generate_metadata] ||= false
  end

  # Whether the override_proto_namespaces parameter was given in the configuration
  def override_proto_namespaces_defined?
    configuration.key? :override_proto_namespaces
  end

  # Sets the override_proto_namespaces parameter in the configuration
  def override_proto_namespaces= value
    configuration[:override_proto_namespaces] = value
  end

  # Whether namespace overrides apply to proto/grpc class references
  def override_proto_namespaces?
    configuration[:override_proto_namespaces] ||= false
  end

  # Raw parsed json of the combined grpc service config files if provided
  # or an empty hash if no config was provided
  def grpc_service_config_raw
    @grpc_service_config_raw ||= begin
      filenames = protoc_options["grpc_service_config"].to_s.split ";"
      filenames.inject({}) do |running_hash, filename|
        file_hash = JSON.parse ::File.read filename
        deep_merge running_hash, file_hash
      end
    end
  end

  # Parsed grpc service config
  def grpc_service_config
    @grpc_service_config ||= Gapic::GrpcServiceConfig::Parser.parse grpc_service_config_raw
  end

  # Raw text of the service.yaml if given as a parameter
  # or nil if no parameter given
  # @return [String]
  def service_config_raw
    @service_config_raw ||= begin
      filename = protoc_options[:service_yaml]
      ::File.read filename if filename
    end
  end

  # Parsed service config
  # @return [Google::Api::Service]
  def service_config
    @service_config ||= Gapic::Schema::ServiceConfigParser.parse_service_yaml service_config_raw
  end

  # Parsed API Metadata model
  # @return [Gapic::Model::ApiMetadata]
  def api_metadata
    @api_metadata ||= begin
      api_metadata = Gapic::Model::ApiMetadata.new
      Gapic::Schema::ServiceConfigParser.parse_api_metadata service_config_raw, api_metadata
      api_metadata.standardize_names!
      api_metadata.standardize_title! gem_name: configuration.fetch(:gem, nil)&.fetch(:name, "")
      api_metadata.standardize_descriptions!
      api_metadata.standardize_auto_populated_fields! @service_config
      api_metadata
    end
  end

  # Get a resource given its type string
  def lookup_resource_type resource_type
    @resource_types[resource_type]
  end

  # Given a service, find all common services that use it as a delegate.
  def common_services_for delegate
    @delegate_to_common ||= (configuration[:common_services] || {}).each_with_object({}) do |(c, d), mapping|
      (mapping[d] ||= []) << c
    end
    all_services = services
    @delegate_to_common.fetch(delegate.address.join("."), []).map do |addr|
      addr = addr.split "."
      all_services.find { |s| s.address == addr }
    end.compact.uniq
  end

  # Given a common service, return its delegate.
  def delegate_service_for common
    addr = (configuration[:common_services] || {})[common.address.join "."]
    return nil unless addr
    addr = addr.split "."
    services.find { |s| s.address == addr }
  end

  ##
  # Returns a model for the nonstandard LRO for a given service
  # The `analyze_nonstandard_lros` method fills in the model cache
  #
  # @param service_full_name [String]
  #
  # @return [Gapic::Model::Service::NonstandardLroProvider, Gapic::Model::Service::NoNonstandardLro]
  def nonstandard_lro_model_for service_full_name
    if @nonstandard_lro_services.key? service_full_name
      @nonstandard_lro_services[service_full_name]
    else
      Gapic::Model::Service::NoNonstandardLro.instance
    end
  end

  ##
  # Whether configuration has an override for the wrapper gem name
  # @return [Boolean]
  def wrapper_gem_name_override?
    configuration.key?(:overrides) &&
      configuration[:overrides].key?(:wrapper_gem_name)
  end

  ##
  # An override for the wrapper gem name in the configuration
  # @return [String, nil]
  def wrapper_gem_name_override
    return nil unless wrapper_gem_name_override?
    return nil if configuration[:overrides][:wrapper_gem_name].nil?

    wrapper_name_config = configuration[:overrides][:wrapper_gem_name].strip
    return nil if wrapper_name_config.empty?

    wrapper_name_config
  end

  private

  # Perform a variety of sanity checks on the data, and prints errors to
  # the given output as appropriate.
  #
  # @param output [IO] Stream to write outputs to.
  def sanity_checks output
    addrs = services.map { |service| service.address.join "." }
    configuration[:common_services]&.each do |k, v|
      output.puts "WARNING: configured common service #{k} is not present" unless addrs.include? k
      output.puts "WARNING: configured common service delegate #{v} is not present" unless addrs.include? v
    end
    # TODO: Sanity check snippet configs to ensure that the type of call
    # (e.g. streaming, lro, etc) matches the rpc type. Warn and remove any
    # noncomplying snippet configs to prevent crashes when rendering.
  end

  # Does a pre-analysis of all resources defined in the job. This has
  # two effects:
  # * Side effect: each resource has its parent_resources field set.
  # * A mapping from resource type to resource wrapper is returned.
  def analyze_resources
    # In order to set parent_resources, we first populate a mapping from
    # parsed pattern to resources that use it (in the patterns variable).
    # Note that there may be multiple resources associated with a pattern.
    # (This is uncommon, but one example is monitoring v3 which uses
    # "projects/*" for its workspace type as well as inheriting the common
    # project type. We thus map each pattern to an array of resources.)
    # Constructing the patterns mapping is done in one pass along with
    # populating the type mapping (which maps only to single resources.)
    # Then, we go through all resources again, get each's expected parent
    # patterns, and anything that shows up in the patterns mapping is taken
    # to be a parent.
    types = {}
    patterns = {}
    @files.each do |file|
      file.resources.each { |resource| populate_resource_lookups resource, types, patterns }
      file.messages.each { |message| populate_message_resource_lookups message, types, patterns }
    end
    types.each_value do |resource|
      parents = resource.parsed_parent_patterns
                        .flat_map { |pat| Array(patterns[pat]) }
                        .uniq
      resource.parent_resources.replace parents
    end
    types
  end

  def populate_resource_lookups resource, types, patterns
    types[resource.type] = resource
    resource.parsed_patterns.each do |pat|
      ((patterns[pat] ||= []) << resource).uniq!
    end
  end

  def populate_message_resource_lookups message, types, patterns
    populate_resource_lookups message.resource, types, patterns if message.resource
    message.nested_messages.each do |nested|
      populate_message_resource_lookups nested, types, patterns
    end
  end

  ##
  # Does a pre-analysis of the nonstandard LRO for every service.
  # For the services that provide nonstandard LRO functionality, cashes a model for the future use
  #
  # @return [Hash<String, Gapic::Model::Service::NonstandardLroProvider>]
  def analyze_nonstandard_lros
    service_registry = {}

    @files.each do |file|
      file.services.each do |service|
        nonstandard_lro = Gapic::Model::Service.parse_nonstandard_lro service
        service_registry[service.full_name] = nonstandard_lro if nonstandard_lro
      end
    end

    service_registry
  end

  # Parse a comma-delimited list of equals-delimited lists of strings, while
  # mapping backslash-escaped commas and equal signs to literal characters.
  # @param str [String]
  # @param error_output [IO] Stream to write outputs to.
  # @return [Array<Gapic::Schema::RequestParameter>]
  def parse_parameter str, parameter_schema, error_output
    Gapic::Schema::RequestParamParser.parse_parameters_string str,
                                                              param_schema: parameter_schema,
                                                              error_output: error_output
  end

  # split the string on periods, but map backslash-escaped periods to
  # literal periods.
  def parse_key str
    str.scan(/\.|\\.|[^.\\]+/)
       .each_with_object([String.new]) do |tok, arr|
         if tok == "."
           arr.append String.new
         elsif tok.start_with? "\\"
           arr.last << tok[1]
         else
           arr.last << tok
         end
         arr
       end
  end

  def str_to_key str
    str = str.to_s
    str.start_with?(":") ? str[1..].to_sym : str
  end

  def key_to_str key
    key.is_a?(::Symbol) ? ":#{key}" : key.to_s
  end

  def deep_merge left, right
    left.merge right do |_k, lt, rt|
      if lt.is_a?(Hash) && rt.is_a?(Hash)
        deep_merge lt, rt
      elsif lt.is_a?(Array) && rt.is_a?(Array)
        lt + rt
      else
        rt
      end
    end
  end
end

#request ⇒ Object

Returns the value of attribute request.



44
45
46
 
# File 'lib/gapic/schema/api.rb', line 44

def request
  @request
end

#services ⇒ Enumerable<Gapic::Schema::Service> (readonly)

Returns:



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
 
# File 'lib/gapic/schema/api.rb', line 43

class Api
  attr_accessor :request
  attr_accessor :files
  attr_reader :snippet_configs

  # Initializes an API object with the file descriptors that represent the
  # API.
  #
  # @param request [Google::Protobuf::Compiler::CodeGeneratorRequest]
  #   The request object.
  # @param parameter_schema [Gapic::Schema::ParameterSchema]
  #   The request parameters schema to use
  # @param error_output [IO] An IO to write any errors/warnings to.
  # @param configuration [Hash] Optional override of configuration.
  def initialize request, parameter_schema: nil, error_output: $stderr, configuration: nil
    @request = request
    loader = Loader.new
    @files = request.proto_file.map do |fd|
      loader.load_file fd, request.file_to_generate.include?(fd.name)
    end
    @files.each { |f| f.parent = self }
    @configuration = configuration
    @resource_types = analyze_resources
    @nonstandard_lro_services = analyze_nonstandard_lros

    parameter_schema ||= Gapic::Generators::DefaultGeneratorParameters.default_schema
    @protoc_parameters = parse_parameter request.parameter, parameter_schema, error_output
    @snippet_configs = loader.load_snippet_configs self.configuration[:snippet_configs_path]
    sanity_checks error_output
  end

  def containing_api
    self
  end

  def containing_file
    nil
  end

  def lookup address
    address = address.join "." if address.is_a? Array
    @files.each do |f|
      lookup = f.lookup address
      return lookup if lookup
    end
    nil
  end

  def file_for address
    address = address.join "." if address.is_a? Array
    matching_files = @files.select { |f| f.lookup address }
    matching_files.first
  end

  def overrides_of key
    configuration&.dig(:overrides, key) || {}
  end

  def fix_file_path str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:file_path].nil?
    configuration[:overrides][:file_path].fetch str, str
  end

  def fix_namespace str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:namespace].nil?
    configuration[:overrides][:namespace].fetch str, str
  end

  def fix_service_name str
    str = String str
    return str if configuration[:overrides].nil?
    return str if configuration[:overrides][:service].nil?
    configuration[:overrides][:service].fetch str, str
  end

  # @return [Enumerable<Gapic::Schema::File>]
  def generate_files
    @files.select(&:generate?)
  end

  # @return [Enumerable<Gapic::Schema::Service>]
  def services
    @files.map(&:services).flatten
  end

  # @return [Enumerable<Gapic::Schema::Message>]
  def messages
    @files.map(&:messages).flatten
  end

  # Structured Hash representation of the parameter values.
  # @return [Hash]
  def protoc_options
    @protoc_options ||= begin
      result = {}
      @protoc_parameters.each do |parameter|
        result[str_to_key(parameter.config_name)] = parameter.config_value
      end
      result
    end
  end

  # Reconstructed string representation of the protoc parameters
  # @return [String]
  def protoc_parameter
    Gapic::Schema::RequestParamParser.reconstruct_parameters_string @protoc_parameters
  end

  # Structured representation of the samples configuration files.
  # @return [Array<Hash>]
  #   An array of the sample file hashes.
  def samples
    @samples ||= protoc_options["samples"].to_s.split(";").flat_map do |sample_path|
      YAML.load_file sample_path
    end.compact
  end

  # Structured representation of the standalone samples configuration files.
  # @return [Array<Hash>]
  #   An array of the standalone sample configuration hashes.
  def standalone_samples
    @standalone_samples ||= begin
      supported_types = [
        "com.google.api.codegen.SampleConfigProto",
        "com.google.api.codegen.samplegen.v1p2.SampleConfigProto"
      ]
      supported_sample_types = [nil, "standalone"]
      samples.select { |sample_file| supported_types.include? sample_file["type"] }
             .select { |sample_file| sample_file["schema_version"] == "1.2.0" }
             .map { |sample_file| sample_file["samples"] }
             .flatten.compact
             .select { |sample_config| supported_sample_types.include? sample_config["sample_type"] }
    end
  end

  # Structured representation of the standalone test samples configuration files.
  # @return [Array<Hash>]
  #   An array of the standalone sample configuration hashes.
  def standalone_test_samples
    @standalone_test_samples ||= begin
      test_samples = samples.select { |sample| sample["type"] == "test/samples" }
      test_samples.select { |sample| sample["schema_version"] == "1" || sample["schema_version"] == 1 }
                  .map { |sample| sample["samples"] }
                  .flatten.compact
    end
  end

  # Structured representation of the inline samples configuration files.
  # @return [Array<Hash>]
  #   An array of the incode sample configuration hashes, sorted by sample_type.
  def incode_samples
    @incode_samples ||= begin
      supported_types = [
        "com.google.api.codegen.SampleConfigProto",
        "com.google.api.codegen.samplegen.v1p2.SampleConfigProto"
      ]
      samples.select { |sample_file| supported_types.include? sample_file["type"] }
             .select { |sample_file| sample_file["schema_version"] == "1.2.0" }
             .map { |sample_file| sample_file["samples"] }
             .flatten.compact
             .select { |sample_config| sample_config["sample_type"]&.start_with? "incode/" }
             .sort_by { |sample_config| sample_config["sample_type"] }
    end
  end

  # Return all snippet configs for the given method address. Returns the
  # empty array if there are no snippet configs.
  # @param address [String] Method address in the form
  #   `proto.package.v1.ServiceName.MethodName`
  # @return [Array<
  #   Google::Cloud::Tools::SnippetGen::ConfigLanguage::V1::SnippetConfig>]
  def snippet_configs_for address
    address = address.join "." if address.is_a? ::Array
    @snippet_configs.find_all do |config|
      rpc = config.rpc
      rpc.api_version.any? do |vers|
        address == "#{rpc.proto_package}.#{vers}.#{rpc.service_name}.#{rpc.rpc_name}"
      end
    end
  end

  # Structured Hash representation of the configuration file.
  # @return [Hash]
  #   A Hash of the configuration values.
  def configuration
    @configuration ||= begin
      config_file = protoc_options["configuration"]
      config = config_file ? YAML.load_file(config_file) : {}
      protoc_options.each do |k, v|
        next if k == "configuration"
        branch = parse_key(key_to_str(k)).reverse.inject(v) { |m, s| { str_to_key(s) => m } }
        config = deep_merge config, branch
      end
      config
    end
  end

  # Whether the generate_path_helpers_output parameter was given in the configuration
  def generate_path_helpers_output_defined?
    configuration.key? :generate_path_helpers_output
  end

  # Sets the generate_path_helpers_output parameter in the configuration
  def generate_path_helpers_output= value
    configuration[:generate_path_helpers_output] = value
  end

  # Whether to generate path helpers for output as well as input messages
  def generate_path_helpers_output?
    # if not set in configuration, false by default
    configuration[:generate_path_helpers_output] ||= false
  end

  # Whether to generate REST clients
  def generate_rest_clients?
    return false if configuration[:transports].nil?
    configuration[:transports].include? "rest"
  end

  # Whether to generate GRPC clients
  def generate_grpc_clients?
    return true if configuration[:transports].nil?
    configuration[:transports].include? "grpc"
  end

  ##
  # The default transport, used when choosing which client class a docs
  # xref should link to.
  #
  # @return [:grpc,:rest]
  #
  def default_transport
    generate_grpc_clients? ? :grpc : :rest
  end

  # Whether to generate standalone snippets
  def generate_standalone_snippets?
    configuration.fetch :generate_standalone_snippets, true
  end

  # Whether to generate inline documentation snippets
  def generate_yardoc_snippets?
    configuration.fetch :generate_yardoc_snippets, true
  end

  # Whether to generate gapic metadata (drift manifest) file
  # @return [Boolean]
  def generate_metadata
    configuration[:generate_metadata] ||= false
  end

  # Whether the override_proto_namespaces parameter was given in the configuration
  def override_proto_namespaces_defined?
    configuration.key? :override_proto_namespaces
  end

  # Sets the override_proto_namespaces parameter in the configuration
  def override_proto_namespaces= value
    configuration[:override_proto_namespaces] = value
  end

  # Whether namespace overrides apply to proto/grpc class references
  def override_proto_namespaces?
    configuration[:override_proto_namespaces] ||= false
  end

  # Raw parsed json of the combined grpc service config files if provided
  # or an empty hash if no config was provided
  def grpc_service_config_raw
    @grpc_service_config_raw ||= begin
      filenames = protoc_options["grpc_service_config"].to_s.split ";"
      filenames.inject({}) do |running_hash, filename|
        file_hash = JSON.parse ::File.read filename
        deep_merge running_hash, file_hash
      end
    end
  end

  # Parsed grpc service config
  def grpc_service_config
    @grpc_service_config ||= Gapic::GrpcServiceConfig::Parser.parse grpc_service_config_raw
  end

  # Raw text of the service.yaml if given as a parameter
  # or nil if no parameter given
  # @return [String]
  def service_config_raw
    @service_config_raw ||= begin
      filename = protoc_options[:service_yaml]
      ::File.read filename if filename
    end
  end

  # Parsed service config
  # @return [Google::Api::Service]
  def service_config
    @service_config ||= Gapic::Schema::ServiceConfigParser.parse_service_yaml service_config_raw
  end

  # Parsed API Metadata model
  # @return [Gapic::Model::ApiMetadata]
  def api_metadata
    @api_metadata ||= begin
      api_metadata = Gapic::Model::ApiMetadata.new
      Gapic::Schema::ServiceConfigParser.parse_api_metadata service_config_raw, api_metadata
      api_metadata.standardize_names!
      api_metadata.standardize_title! gem_name: configuration.fetch(:gem, nil)&.fetch(:name, "")
      api_metadata.standardize_descriptions!
      api_metadata.standardize_auto_populated_fields! @service_config
      api_metadata
    end
  end

  # Get a resource given its type string
  def lookup_resource_type resource_type
    @resource_types[resource_type]
  end

  # Given a service, find all common services that use it as a delegate.
  def common_services_for delegate
    @delegate_to_common ||= (configuration[:common_services] || {}).each_with_object({}) do |(c, d), mapping|
      (mapping[d] ||= []) << c
    end
    all_services = services
    @delegate_to_common.fetch(delegate.address.join("."), []).map do |addr|
      addr = addr.split "."
      all_services.find { |s| s.address == addr }
    end.compact.uniq
  end

  # Given a common service, return its delegate.
  def delegate_service_for common
    addr = (configuration[:common_services] || {})[common.address.join "."]
    return nil unless addr
    addr = addr.split "."
    services.find { |s| s.address == addr }
  end

  ##
  # Returns a model for the nonstandard LRO for a given service
  # The `analyze_nonstandard_lros` method fills in the model cache
  #
  # @param service_full_name [String]
  #
  # @return [Gapic::Model::Service::NonstandardLroProvider, Gapic::Model::Service::NoNonstandardLro]
  def nonstandard_lro_model_for service_full_name
    if @nonstandard_lro_services.key? service_full_name
      @nonstandard_lro_services[service_full_name]
    else
      Gapic::Model::Service::NoNonstandardLro.instance
    end
  end

  ##
  # Whether configuration has an override for the wrapper gem name
  # @return [Boolean]
  def wrapper_gem_name_override?
    configuration.key?(:overrides) &&
      configuration[:overrides].key?(:wrapper_gem_name)
  end

  ##
  # An override for the wrapper gem name in the configuration
  # @return [String, nil]
  def wrapper_gem_name_override
    return nil unless wrapper_gem_name_override?
    return nil if configuration[:overrides][:wrapper_gem_name].nil?

    wrapper_name_config = configuration[:overrides][:wrapper_gem_name].strip
    return nil if wrapper_name_config.empty?

    wrapper_name_config
  end

  private

  # Perform a variety of sanity checks on the data, and prints errors to
  # the given output as appropriate.
  #
  # @param output [IO] Stream to write outputs to.
  def sanity_checks output
    addrs = services.map { |service| service.address.join "." }
    configuration[:common_services]&.each do |k, v|
      output.puts "WARNING: configured common service #{k} is not present" unless addrs.include? k
      output.puts "WARNING: configured common service delegate #{v} is not present" unless addrs.include? v
    end
    # TODO: Sanity check snippet configs to ensure that the type of call
    # (e.g. streaming, lro, etc) matches the rpc type. Warn and remove any
    # noncomplying snippet configs to prevent crashes when rendering.
  end

  # Does a pre-analysis of all resources defined in the job. This has
  # two effects:
  # * Side effect: each resource has its parent_resources field set.
  # * A mapping from resource type to resource wrapper is returned.
  def analyze_resources
    # In order to set parent_resources, we first populate a mapping from
    # parsed pattern to resources that use it (in the patterns variable).
    # Note that there may be multiple resources associated with a pattern.
    # (This is uncommon, but one example is monitoring v3 which uses
    # "projects/*" for its workspace type as well as inheriting the common
    # project type. We thus map each pattern to an array of resources.)
    # Constructing the patterns mapping is done in one pass along with
    # populating the type mapping (which maps only to single resources.)
    # Then, we go through all resources again, get each's expected parent
    # patterns, and anything that shows up in the patterns mapping is taken
    # to be a parent.
    types = {}
    patterns = {}
    @files.each do |file|
      file.resources.each { |resource| populate_resource_lookups resource, types, patterns }
      file.messages.each { |message| populate_message_resource_lookups message, types, patterns }
    end
    types.each_value do |resource|
      parents = resource.parsed_parent_patterns
                        .flat_map { |pat| Array(patterns[pat]) }
                        .uniq
      resource.parent_resources.replace parents
    end
    types
  end

  def populate_resource_lookups resource, types, patterns
    types[resource.type] = resource
    resource.parsed_patterns.each do |pat|
      ((patterns[pat] ||= []) << resource).uniq!
    end
  end

  def populate_message_resource_lookups message, types, patterns
    populate_resource_lookups message.resource, types, patterns if message.resource
    message.nested_messages.each do |nested|
      populate_message_resource_lookups nested, types, patterns
    end
  end

  ##
  # Does a pre-analysis of the nonstandard LRO for every service.
  # For the services that provide nonstandard LRO functionality, cashes a model for the future use
  #
  # @return [Hash<String, Gapic::Model::Service::NonstandardLroProvider>]
  def analyze_nonstandard_lros
    service_registry = {}

    @files.each do |file|
      file.services.each do |service|
        nonstandard_lro = Gapic::Model::Service.parse_nonstandard_lro service
        service_registry[service.full_name] = nonstandard_lro if nonstandard_lro
      end
    end

    service_registry
  end

  # Parse a comma-delimited list of equals-delimited lists of strings, while
  # mapping backslash-escaped commas and equal signs to literal characters.
  # @param str [String]
  # @param error_output [IO] Stream to write outputs to.
  # @return [Array<Gapic::Schema::RequestParameter>]
  def parse_parameter str, parameter_schema, error_output
    Gapic::Schema::RequestParamParser.parse_parameters_string str,
                                                              param_schema: parameter_schema,
                                                              error_output: error_output
  end

  # split the string on periods, but map backslash-escaped periods to
  # literal periods.
  def parse_key str
    str.scan(/\.|\\.|[^.\\]+/)
       .each_with_object([String.new]) do |tok, arr|
         if tok == "."
           arr.append String.new
         elsif tok.start_with? "\\"
           arr.last << tok[1]
         else
           arr.last << tok
         end
         arr
       end
  end

  def str_to_key str
    str = str.to_s
    str.start_with?(":") ? str[1..].to_sym : str
  end

  def key_to_str key
    key.is_a?(::Symbol) ? ":#{key}" : key.to_s
  end

  def deep_merge left, right
    left.merge right do |_k, lt, rt|
      if lt.is_a?(Hash) && rt.is_a?(Hash)
        deep_merge lt, rt
      elsif lt.is_a?(Array) && rt.is_a?(Array)
        lt + rt
      else
        rt
      end
    end
  end
end

#snippet_configs ⇒ Object (readonly)

Returns the value of attribute snippet_configs.



46
47
48
 
# File 'lib/gapic/schema/api.rb', line 46

def snippet_configs
  @snippet_configs
end

Instance Method Details

#api_metadata ⇒ Gapic::Model::ApiMetadata

Parsed API Metadata model

Returns:



348
349
350
351
352
353
354
355
356
357
358
 
# File 'lib/gapic/schema/api.rb', line 348

def api_metadata
  @api_metadata ||= begin
    api_metadata = Gapic::Model::ApiMetadata.new
    Gapic::Schema::ServiceConfigParser.parse_api_metadata service_config_raw, api_metadata
    api_metadata.standardize_names!
    api_metadata.standardize_title! gem_name: configuration.fetch(:gem, nil)&.fetch(:name, "")
    api_metadata.standardize_descriptions!
    api_metadata.standardize_auto_populated_fields! @service_config
    api_metadata
  end
end

#common_services_for(delegate) ⇒ Object

Given a service, find all common services that use it as a delegate.



366
367
368
369
370
371
372
373
374
375
 
# File 'lib/gapic/schema/api.rb', line 366

def common_services_for delegate
  @delegate_to_common ||= (configuration[:common_services] || {}).each_with_object({}) do |(c, d), mapping|
    (mapping[d] ||= []) << c
  end
  all_services = services
  @delegate_to_common.fetch(delegate.address.join("."), []).map do |addr|
    addr = addr.split "."
    all_services.find { |s| s.address == addr }
  end.compact.uniq
end

#configuration ⇒ Hash

Structured Hash representation of the configuration file.

Returns:

  • (Hash) —

    A Hash of the configuration values.



231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/gapic/schema/api.rb', line 231

def configuration
  @configuration ||= begin
    config_file = protoc_options["configuration"]
    config = config_file ? YAML.load_file(config_file) : {}
    protoc_options.each do |k, v|
      next if k == "configuration"
      branch = parse_key(key_to_str(k)).reverse.inject(v) { |m, s| { str_to_key(s) => m } }
      config = deep_merge config, branch
    end
    config
  end
end

#containing_api ⇒ Object 



74
75
76
 
# File 'lib/gapic/schema/api.rb', line 74

def containing_api
  self
end

#containing_file ⇒ Object 



78
79
80
 
# File 'lib/gapic/schema/api.rb', line 78

def containing_file
  nil
end

#default_transport ⇒ :grpc, :rest

The default transport, used when choosing which client class a docs xref should link to.

Returns:

  • (:grpc, :rest) 


278
279
280
 
# File 'lib/gapic/schema/api.rb', line 278

def default_transport
  generate_grpc_clients? ? :grpc : :rest
end

#delegate_service_for(common) ⇒ Object

Given a common service, return its delegate.



378
379
380
381
382
383
 
# File 'lib/gapic/schema/api.rb', line 378

def delegate_service_for common
  addr = (configuration[:common_services] || {})[common.address.join "."]
  return nil unless addr
  addr = addr.split "."
  services.find { |s| s.address == addr }
end

#file_for(address) ⇒ Object 



91
92
93
94
95
 
# File 'lib/gapic/schema/api.rb', line 91

def file_for address
  address = address.join "." if address.is_a? Array
  matching_files = @files.select { |f| f.lookup address }
  matching_files.first
end

#fix_file_path(str) ⇒ Object 



101
102
103
104
105
106
 
# File 'lib/gapic/schema/api.rb', line 101

def fix_file_path str
  str = String str
  return str if configuration[:overrides].nil?
  return str if configuration[:overrides][:file_path].nil?
  configuration[:overrides][:file_path].fetch str, str
end

#fix_namespace(str) ⇒ Object 



108
109
110
111
112
113
 
# File 'lib/gapic/schema/api.rb', line 108

def fix_namespace str
  str = String str
  return str if configuration[:overrides].nil?
  return str if configuration[:overrides][:namespace].nil?
  configuration[:overrides][:namespace].fetch str, str
end

#fix_service_name(str) ⇒ Object 



115
116
117
118
119
120
 
# File 'lib/gapic/schema/api.rb', line 115

def fix_service_name str
  str = String str
  return str if configuration[:overrides].nil?
  return str if configuration[:overrides][:service].nil?
  configuration[:overrides][:service].fetch str, str
end

#generate_files ⇒ Enumerable<Gapic::Schema::File>

Returns:



123
124
125
 
# File 'lib/gapic/schema/api.rb', line 123

def generate_files
  @files.select(&:generate?)
end

#generate_grpc_clients? ⇒ Boolean

Whether to generate GRPC clients

Returns:

  • (Boolean) 


267
268
269
270
 
# File 'lib/gapic/schema/api.rb', line 267

def generate_grpc_clients?
  return true if configuration[:transports].nil?
  configuration[:transports].include? "grpc"
end

#generate_metadata ⇒ Boolean

Whether to generate gapic metadata (drift manifest) file

Returns:

  • (Boolean) 


294
295
296
 
# File 'lib/gapic/schema/api.rb', line 294

def generate_metadata
  configuration[:generate_metadata] ||= false
end

#generate_path_helpers_output=(value) ⇒ Object

Sets the generate_path_helpers_output parameter in the configuration



250
251
252
 
# File 'lib/gapic/schema/api.rb', line 250

def generate_path_helpers_output= value
  configuration[:generate_path_helpers_output] = value
end

#generate_path_helpers_output? ⇒ Boolean

Whether to generate path helpers for output as well as input messages

Returns:

  • (Boolean) 


255
256
257
258
 
# File 'lib/gapic/schema/api.rb', line 255

def generate_path_helpers_output?
  # if not set in configuration, false by default
  configuration[:generate_path_helpers_output] ||= false
end

#generate_path_helpers_output_defined? ⇒ Boolean

Whether the generate_path_helpers_output parameter was given in the configuration

Returns:

  • (Boolean) 


245
246
247
 
# File 'lib/gapic/schema/api.rb', line 245

def generate_path_helpers_output_defined?
  configuration.key? :generate_path_helpers_output
end

#generate_rest_clients? ⇒ Boolean

Whether to generate REST clients

Returns:

  • (Boolean) 


261
262
263
264
 
# File 'lib/gapic/schema/api.rb', line 261

def generate_rest_clients?
  return false if configuration[:transports].nil?
  configuration[:transports].include? "rest"
end

#generate_standalone_snippets? ⇒ Boolean

Whether to generate standalone snippets

Returns:

  • (Boolean) 


283
284
285
 
# File 'lib/gapic/schema/api.rb', line 283

def generate_standalone_snippets?
  configuration.fetch :generate_standalone_snippets, true
end

#generate_yardoc_snippets? ⇒ Boolean

Whether to generate inline documentation snippets

Returns:

  • (Boolean) 


288
289
290
 
# File 'lib/gapic/schema/api.rb', line 288

def generate_yardoc_snippets?
  configuration.fetch :generate_yardoc_snippets, true
end

#grpc_service_config ⇒ Object

Parsed grpc service config



326
327
328
 
# File 'lib/gapic/schema/api.rb', line 326

def grpc_service_config
  @grpc_service_config ||= Gapic::GrpcServiceConfig::Parser.parse grpc_service_config_raw
end

#grpc_service_config_raw ⇒ Object

Raw parsed json of the combined grpc service config files if provided or an empty hash if no config was provided



315
316
317
318
319
320
321
322
323
 
# File 'lib/gapic/schema/api.rb', line 315

def grpc_service_config_raw
  @grpc_service_config_raw ||= begin
    filenames = protoc_options["grpc_service_config"].to_s.split ";"
    filenames.inject({}) do |running_hash, filename|
      file_hash = JSON.parse ::File.read filename
      deep_merge running_hash, file_hash
    end
  end
end

#incode_samples ⇒ Array<Hash>

Structured representation of the inline samples configuration files.

Returns:

  • (Array<Hash>) —

    An array of the incode sample configuration hashes, sorted by sample_type.



197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/gapic/schema/api.rb', line 197

def incode_samples
  @incode_samples ||= begin
    supported_types = [
      "com.google.api.codegen.SampleConfigProto",
      "com.google.api.codegen.samplegen.v1p2.SampleConfigProto"
    ]
    samples.select { |sample_file| supported_types.include? sample_file["type"] }
           .select { |sample_file| sample_file["schema_version"] == "1.2.0" }
           .map { |sample_file| sample_file["samples"] }
           .flatten.compact
           .select { |sample_config| sample_config["sample_type"]&.start_with? "incode/" }
           .sort_by { |sample_config| sample_config["sample_type"] }
  end
end

#lookup(address) ⇒ Object 



82
83
84
85
86
87
88
89
 
# File 'lib/gapic/schema/api.rb', line 82

def lookup address
  address = address.join "." if address.is_a? Array
  @files.each do |f|
    lookup = f.lookup address
    return lookup if lookup
  end
  nil
end

#lookup_resource_type(resource_type) ⇒ Object

Get a resource given its type string



361
362
363
 
# File 'lib/gapic/schema/api.rb', line 361

def lookup_resource_type resource_type
  @resource_types[resource_type]
end

#nonstandard_lro_model_for(service_full_name) ⇒ Gapic::Model::Service::NonstandardLroProvider, Gapic::Model::Service::NoNonstandardLro

Returns a model for the nonstandard LRO for a given service The analyze_nonstandard_lros method fills in the model cache

Parameters:

  • service_full_name (String)

Returns:



392
393
394
395
396
397
398
 
# File 'lib/gapic/schema/api.rb', line 392

def nonstandard_lro_model_for service_full_name
  if @nonstandard_lro_services.key? service_full_name
    @nonstandard_lro_services[service_full_name]
  else
    Gapic::Model::Service::NoNonstandardLro.instance
  end
end

#override_proto_namespaces=(value) ⇒ Object

Sets the override_proto_namespaces parameter in the configuration



304
305
306
 
# File 'lib/gapic/schema/api.rb', line 304

def override_proto_namespaces= value
  configuration[:override_proto_namespaces] = value
end

#override_proto_namespaces? ⇒ Boolean

Whether namespace overrides apply to proto/grpc class references

Returns:

  • (Boolean) 


309
310
311
 
# File 'lib/gapic/schema/api.rb', line 309

def override_proto_namespaces?
  configuration[:override_proto_namespaces] ||= false
end

#override_proto_namespaces_defined? ⇒ Boolean

Whether the override_proto_namespaces parameter was given in the configuration

Returns:

  • (Boolean) 


299
300
301
 
# File 'lib/gapic/schema/api.rb', line 299

def override_proto_namespaces_defined?
  configuration.key? :override_proto_namespaces
end

#overrides_of(key) ⇒ Object 



97
98
99
 
# File 'lib/gapic/schema/api.rb', line 97

def overrides_of key
  configuration&.dig(:overrides, key) || {}
end

#protoc_options ⇒ Hash

Structured Hash representation of the parameter values.

Returns:

  • (Hash) 


139
140
141
142
143
144
145
146
147
 
# File 'lib/gapic/schema/api.rb', line 139

def protoc_options
  @protoc_options ||= begin
    result = {}
    @protoc_parameters.each do |parameter|
      result[str_to_key(parameter.config_name)] = parameter.config_value
    end
    result
  end
end

#protoc_parameter ⇒ String

Reconstructed string representation of the protoc parameters

Returns:

  • (String) 


151
152
153
 
# File 'lib/gapic/schema/api.rb', line 151

def protoc_parameter
  Gapic::Schema::RequestParamParser.reconstruct_parameters_string @protoc_parameters
end

#samples ⇒ Array<Hash>

Structured representation of the samples configuration files.

Returns:

  • (Array<Hash>) —

    An array of the sample file hashes.



158
159
160
161
162
 
# File 'lib/gapic/schema/api.rb', line 158

def samples
  @samples ||= protoc_options["samples"].to_s.split(";").flat_map do |sample_path|
    YAML.load_file sample_path
  end.compact
end

#service_config ⇒ Google::Api::Service

Parsed service config

Returns:

  • (Google::Api::Service) 


342
343
344
 
# File 'lib/gapic/schema/api.rb', line 342

def service_config
  @service_config ||= Gapic::Schema::ServiceConfigParser.parse_service_yaml service_config_raw
end

#service_config_raw ⇒ String

Raw text of the service.yaml if given as a parameter or nil if no parameter given

Returns:

  • (String) 


333
334
335
336
337
338
 
# File 'lib/gapic/schema/api.rb', line 333

def service_config_raw
  @service_config_raw ||= begin
    filename = protoc_options[:service_yaml]
    ::File.read filename if filename
  end
end

#snippet_configs_for(address) ⇒ Array< Google::Cloud::Tools::SnippetGen::ConfigLanguage::V1::SnippetConfig>

Return all snippet configs for the given method address. Returns the empty array if there are no snippet configs.

Parameters:

  • address (String) —

    Method address in the form proto.package.v1.ServiceName.MethodName

Returns:



218
219
220
221
222
223
224
225
226
 
# File 'lib/gapic/schema/api.rb', line 218

def snippet_configs_for address
  address = address.join "." if address.is_a? ::Array
  @snippet_configs.find_all do |config|
    rpc = config.rpc
    rpc.api_version.any? do |vers|
      address == "#{rpc.proto_package}.#{vers}.#{rpc.service_name}.#{rpc.rpc_name}"
    end
  end
end

#standalone_samples ⇒ Array<Hash>

Structured representation of the standalone samples configuration files.

Returns:

  • (Array<Hash>) —

    An array of the standalone sample configuration hashes.



167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/gapic/schema/api.rb', line 167

def standalone_samples
  @standalone_samples ||= begin
    supported_types = [
      "com.google.api.codegen.SampleConfigProto",
      "com.google.api.codegen.samplegen.v1p2.SampleConfigProto"
    ]
    supported_sample_types = [nil, "standalone"]
    samples.select { |sample_file| supported_types.include? sample_file["type"] }
           .select { |sample_file| sample_file["schema_version"] == "1.2.0" }
           .map { |sample_file| sample_file["samples"] }
           .flatten.compact
           .select { |sample_config| supported_sample_types.include? sample_config["sample_type"] }
  end
end

#standalone_test_samples ⇒ Array<Hash>

Structured representation of the standalone test samples configuration files.

Returns:

  • (Array<Hash>) —

    An array of the standalone sample configuration hashes.



185
186
187
188
189
190
191
192
 
# File 'lib/gapic/schema/api.rb', line 185

def standalone_test_samples
  @standalone_test_samples ||= begin
    test_samples = samples.select { |sample| sample["type"] == "test/samples" }
    test_samples.select { |sample| sample["schema_version"] == "1" || sample["schema_version"] == 1 }
                .map { |sample| sample["samples"] }
                .flatten.compact
  end
end

#wrapper_gem_name_override ⇒ String?

An override for the wrapper gem name in the configuration

Returns:

  • (String, nil) 


411
412
413
414
415
416
417
418
419
 
# File 'lib/gapic/schema/api.rb', line 411

def wrapper_gem_name_override
  return nil unless wrapper_gem_name_override?
  return nil if configuration[:overrides][:wrapper_gem_name].nil?

  wrapper_name_config = configuration[:overrides][:wrapper_gem_name].strip
  return nil if wrapper_name_config.empty?

  wrapper_name_config
end

#wrapper_gem_name_override? ⇒ Boolean

Whether configuration has an override for the wrapper gem name

Returns:

  • (Boolean) 


403
404
405
406
 
# File 'lib/gapic/schema/api.rb', line 403

def wrapper_gem_name_override?
  configuration.key?(:overrides) &&
    configuration[:overrides].key?(:wrapper_gem_name)
end