diff --git a/Gemfile b/Gemfile index f2df490..40f32f6 100644 --- a/Gemfile +++ b/Gemfile @@ -1,3 +1,3 @@ source 'https://rubygems.org' -gem 'nhtsa_vin' \ No newline at end of file +# No extra gems: VIN decoding talks to NHTSA's vPIC service directly (app/services/vin_decoder.rb) diff --git a/app/jobs/vehicle_vin_decode_job.rb b/app/jobs/vehicle_vin_decode_job.rb index 787a60c..74f5a71 100644 --- a/app/jobs/vehicle_vin_decode_job.rb +++ b/app/jobs/vehicle_vin_decode_job.rb @@ -23,7 +23,8 @@ class VehicleVinDecodeJob < ApplicationJob log "Looking up VIN for vehicle ##{vehicle_id}" vehicle = Vehicle.find_by(id: vehicle_id) return unless vehicle&.vin.present? - result = VinDecoder.call(vehicle.vin) + # The year on file (if someone entered one) helps NHTSA, especially for older vehicles + result = VinDecoder.call(vehicle.vin, model_year: vehicle.year) unless result.success? log "Failed to decode vin" diff --git a/app/services/vin_decoder.rb b/app/services/vin_decoder.rb index 2e00c85..87230c1 100644 --- a/app/services/vin_decoder.rb +++ b/app/services/vin_decoder.rb @@ -8,37 +8,152 @@ # #THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +require 'json' +require 'net/http' +require 'openssl' +require 'timeout' + +# Decodes VINs with NHTSA's free vPIC service (https://vpic.nhtsa.dot.gov/api/), no API key needed. +# +# result = VinDecoder.call("1C4HJXFG0JW123456", model_year: 2018) +# result.success? # => true +# result.data # => # +# +# - Invalid VINs and VINs NHTSA can't decode come back as a failure with NHTSA's explanation (final). +# - Network trouble, timeouts and NHTSA outages raise TransientError so the job can retry later. +# - NHTSA flags some decodes with warnings (e.g. a wrong check digit) but still returns the vehicle; +# those count as decoded, and the warning is kept in data.warning. class VinDecoder Result = Struct.new(:success?, :data, :error) - # Raised when the lookup itself fails (network trouble, NHTSA down). Unlike an invalid VIN or "no match", - # this is worth retrying, so it's raised for the job to retry instead of being returned as a failure. + # Decoded vehicle details, with the same field names the old nhtsa_vin gem provided + Vehicle = Struct.new(:year, :make, :model, :trim, :doors, :body_class, :engine, :warning, keyword_init: true) + + # Raised when the lookup itself fails (network, timeout, NHTSA down or throttling). Worth retrying. class TransientError < StandardError; end - def self.call(vin) - new(vin).call + ENDPOINT = 'https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinValues/' + OPEN_TIMEOUT = 5 # seconds + READ_TIMEOUT = 20 # vPIC can take several seconds + + # Characters allowed in a VIN (I, O and Q are never used) + VIN_FORMAT = /\A[A-HJ-NPR-Z0-9]+\z/ + + NETWORK_ERRORS = [ + SocketError, Timeout::Error, IOError, EOFError, SystemCallError, + OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::ProtocolError, JSON::ParserError + ].freeze + + def self.call(vin, model_year: nil) + new(vin, model_year: model_year).call end - def initialize(vin) - @vin = vin + def initialize(vin, model_year: nil) + @vin = vin.to_s.strip.upcase + @model_year = model_year.to_i.positive? ? model_year.to_i : nil end def call - log "Decoding VIN" - validation = NhtsaVin.validate(@vin) - return failure(validation.error) unless validation.valid? + log "Decoding VIN #{@vin}" + return failure('VIN is blank') if @vin.empty? + return failure("VIN contains invalid characters (I, O and Q are never used)") unless @vin.match?(VIN_FORMAT) + return failure("VIN is too long (#{@vin.length} characters, at most 17)") if @vin.length > 17 - query = NhtsaVin.get(@vin) - return failure(query.error) unless query.valid? + record = fetch_record + vehicle = build_vehicle(record) - success(query.response) - rescue StandardError => e - log "VIN lookup error for #{@vin}: #{e.class}: #{e.message}" - raise TransientError, e.message + if vehicle.make.blank? || vehicle.model.blank? + failure(error_text(record).presence || 'NHTSA could not decode this VIN') + else + log "Decoded #{@vin}: #{vehicle.year} #{vehicle.make} #{vehicle.model}#{" (#{vehicle.warning})" if vehicle.warning}" + success(vehicle) + end end private + # Calls vPIC and returns the single result record (a Hash of NHTSA field names to values) + def fetch_record + body = http_get(request_uri) + record = Array(JSON.parse(body)['Results']).first + raise TransientError, 'NHTSA returned no results' unless record.is_a?(Hash) + + record + rescue *NETWORK_ERRORS => e + raise TransientError, "NHTSA lookup failed: #{e.class}: #{e.message}" + end + + def request_uri + uri = URI.join(ENDPOINT, URI.encode_www_form_component(@vin)) + params = { format: 'json' } + params[:modelyear] = @model_year if @model_year # NHTSA recommends sending it; helps pre-1980 VINs + uri.query = URI.encode_www_form(params) + uri + end + + # Separate method so tests can stand in for the network + def http_get(uri) + response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', + open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT) do |http| + request = Net::HTTP::Get.new(uri) + request['Accept'] = 'application/json' + request['User-Agent'] = 'redmine_qbo_vehicles' + http.request(request) + end + + case response + when Net::HTTPSuccess then response.body + when Net::HTTPTooManyRequests, Net::HTTPForbidden, Net::HTTPServerError + raise TransientError, "NHTSA returned HTTP #{response.code}" # throttled or down: retry later + else + raise TransientError, "NHTSA returned unexpected HTTP #{response.code}" + end + end + + def build_vehicle(record) + Vehicle.new( + year: record['ModelYear'].to_i.positive? ? record['ModelYear'].to_i : nil, + make: format_make(record['Make']), + model: clean(record['Model']), + trim: clean(record['Trim']).presence || clean(record['Series']), + doors: clean(record['Doors']), + body_class: clean(record['BodyClass']), + engine: engine_description(record), + warning: warning_text(record) + ) + end + + # NHTSA sends makes in capitals ("JEEP", "LAND ROVER", "MERCEDES-BENZ"). Short ones are usually + # abbreviations (GMC, RAM, BMW, KIA) and stay as they are; longer words are capitalized. + def format_make(make) + clean(make).split(' ').map do |word| + word.split('-').map { |part| part.length <= 3 ? part : part.capitalize }.join('-') + end.join(' ') + end + + def engine_description(record) + liters = clean(record['DisplacementL']) + liters = format('%.1fL', liters.to_f) if liters.present? && liters.to_f.positive? + cylinders = clean(record['EngineCylinders']) + [liters.presence, (cylinders.present? ? "#{cylinders} cyl" : nil)].compact.join(' ').presence + end + + # NHTSA's ErrorCode is "0" for a clean decode; anything else comes with an explanation in ErrorText + def warning_text(record) + codes = clean(record['ErrorCode']).split(',').map(&:strip) + return nil if codes.empty? || codes == ['0'] + + error_text(record) + end + + def error_text(record) + clean(record['ErrorText']).truncate(255) + end + + def clean(value) + value.to_s.strip + end + def success(data) Result.new(true, data, nil) end @@ -51,4 +166,4 @@ class VinDecoder def log(msg) Rails.logger.info "[VinDecoder] #{msg}" end -end \ No newline at end of file +end