Merge pull request 'added backup/restore feature' (#1) from feature_backup-restore into main
Reviewed-on: #1
This commit was merged in pull request #1.
This commit is contained in:
@@ -33,3 +33,7 @@
|
|||||||
# Ignore key files for decrypting credentials and more.
|
# Ignore key files for decrypting credentials and more.
|
||||||
/config/*.key
|
/config/*.key
|
||||||
|
|
||||||
|
|
||||||
|
# Ignore emacs backups
|
||||||
|
*.#
|
||||||
|
*#
|
||||||
|
|||||||
@@ -0,0 +1,3 @@
|
|||||||
|
# Directions to get a running docker image
|
||||||
|
|
||||||
|
Clone the repo
|
||||||
@@ -0,0 +1,45 @@
|
|||||||
|
require "stringio"
|
||||||
|
require "zlib"
|
||||||
|
|
||||||
|
class BackupsController < ApplicationController
|
||||||
|
def show
|
||||||
|
end
|
||||||
|
|
||||||
|
def download
|
||||||
|
send_data gzip(BackupExport.call),
|
||||||
|
filename: "car-tracker-backup-#{Time.current.strftime('%Y%m%d%H%M%S')}.yml.gz",
|
||||||
|
type: "application/gzip",
|
||||||
|
disposition: "attachment"
|
||||||
|
end
|
||||||
|
|
||||||
|
def restore
|
||||||
|
BackupImport.call(gunzip(uploaded_backup.read), mode: params[:mode])
|
||||||
|
redirect_to backup_path, notice: "Backup restored."
|
||||||
|
rescue BackupImport::Error, Zlib::GzipFile::Error => error
|
||||||
|
redirect_to backup_path, alert: "Backup could not be restored: #{restore_error_message(error)}"
|
||||||
|
end
|
||||||
|
|
||||||
|
private
|
||||||
|
|
||||||
|
def uploaded_backup
|
||||||
|
params.fetch(:backup_file)
|
||||||
|
rescue KeyError
|
||||||
|
raise BackupImport::Error, "Choose a backup file to restore."
|
||||||
|
end
|
||||||
|
|
||||||
|
def gzip(content)
|
||||||
|
buffer = StringIO.new
|
||||||
|
Zlib::GzipWriter.wrap(buffer) { |gzip| gzip.write(content) }
|
||||||
|
buffer.string
|
||||||
|
end
|
||||||
|
|
||||||
|
def gunzip(content)
|
||||||
|
Zlib::GzipReader.wrap(StringIO.new(content), &:read)
|
||||||
|
rescue Zlib::GzipFile::Error
|
||||||
|
raise BackupImport::Error, "Backup file must be a gzip-compressed YAML file."
|
||||||
|
end
|
||||||
|
|
||||||
|
def restore_error_message(error)
|
||||||
|
error.message.presence || "unknown error"
|
||||||
|
end
|
||||||
|
end
|
||||||
@@ -0,0 +1,105 @@
|
|||||||
|
class BackupExport
|
||||||
|
FORMAT = "car_tracker_backup".freeze
|
||||||
|
VERSION = 1
|
||||||
|
|
||||||
|
def self.call
|
||||||
|
new.call
|
||||||
|
end
|
||||||
|
|
||||||
|
def call
|
||||||
|
{
|
||||||
|
"format" => FORMAT,
|
||||||
|
"version" => VERSION,
|
||||||
|
"exported_at" => Time.current.iso8601,
|
||||||
|
"vehicles" => vehicles
|
||||||
|
}.to_yaml
|
||||||
|
end
|
||||||
|
|
||||||
|
private
|
||||||
|
|
||||||
|
def vehicles
|
||||||
|
Vehicle.includes(
|
||||||
|
:maintenance_schedules,
|
||||||
|
{ fuel_entries: :updated_by_user },
|
||||||
|
{ maintenance_entries: :updated_by_user }
|
||||||
|
).order(:make, :model, :year, :vin).map do |vehicle|
|
||||||
|
vehicle_data(vehicle)
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
def vehicle_data(vehicle)
|
||||||
|
{
|
||||||
|
"vin" => vehicle.vin,
|
||||||
|
"licence_plate" => vehicle.licence_plate,
|
||||||
|
"make" => vehicle.make,
|
||||||
|
"model" => vehicle.model,
|
||||||
|
"year" => vehicle.year,
|
||||||
|
"color" => vehicle.color,
|
||||||
|
"current_odometer" => vehicle.current_odometer,
|
||||||
|
"fuel_tank_size" => decimal_string(vehicle.fuel_tank_size),
|
||||||
|
"active" => vehicle.active?,
|
||||||
|
"maintenance_schedules" => maintenance_schedules(vehicle),
|
||||||
|
"fuel_entries" => fuel_entries(vehicle),
|
||||||
|
"maintenance_entries" => maintenance_entries(vehicle)
|
||||||
|
}
|
||||||
|
end
|
||||||
|
|
||||||
|
def maintenance_schedules(vehicle)
|
||||||
|
vehicle.maintenance_schedules.sort_by(&:maintenance_type).map do |schedule|
|
||||||
|
{
|
||||||
|
"maintenance_type" => schedule.maintenance_type,
|
||||||
|
"mileage_interval" => schedule.mileage_interval,
|
||||||
|
"time_interval" => schedule.time_interval,
|
||||||
|
"baseline_odometer" => schedule.baseline_odometer,
|
||||||
|
"baseline_date" => date_string(schedule.baseline_date),
|
||||||
|
"active" => schedule.active?,
|
||||||
|
"last_status" => schedule.last_status,
|
||||||
|
"last_status_changed_at" => time_string(schedule.last_status_changed_at)
|
||||||
|
}
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
def fuel_entries(vehicle)
|
||||||
|
vehicle.fuel_entries.sort_by { |entry| [ entry.date, entry.odometer, entry.id ] }.map do |entry|
|
||||||
|
{
|
||||||
|
"date" => date_string(entry.date),
|
||||||
|
"odometer" => entry.odometer,
|
||||||
|
"gallons_pumped" => decimal_string(entry.gallons_pumped),
|
||||||
|
"price_paid" => decimal_string(entry.price_paid),
|
||||||
|
"updated_by_user" => user_data(entry.updated_by_user)
|
||||||
|
}
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
def maintenance_entries(vehicle)
|
||||||
|
vehicle.maintenance_entries.sort_by { |entry| [ entry.date, entry.odometer, entry.name, entry.id ] }.map do |entry|
|
||||||
|
{
|
||||||
|
"name" => entry.name,
|
||||||
|
"notes" => entry.notes,
|
||||||
|
"date" => date_string(entry.date),
|
||||||
|
"odometer" => entry.odometer,
|
||||||
|
"cost" => decimal_string(entry.cost),
|
||||||
|
"updated_by_user" => user_data(entry.updated_by_user)
|
||||||
|
}
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
def user_data(user)
|
||||||
|
{
|
||||||
|
"name" => user.name,
|
||||||
|
"email" => user.email
|
||||||
|
}
|
||||||
|
end
|
||||||
|
|
||||||
|
def date_string(value)
|
||||||
|
value&.iso8601
|
||||||
|
end
|
||||||
|
|
||||||
|
def time_string(value)
|
||||||
|
value&.iso8601
|
||||||
|
end
|
||||||
|
|
||||||
|
def decimal_string(value)
|
||||||
|
value&.to_s("F")
|
||||||
|
end
|
||||||
|
end
|
||||||
@@ -0,0 +1,259 @@
|
|||||||
|
class BackupImport
|
||||||
|
SUPPORTED_VERSION = 1
|
||||||
|
MODES = %w[merge replace].freeze
|
||||||
|
|
||||||
|
class Error < StandardError; end
|
||||||
|
|
||||||
|
def self.call(yaml, mode:)
|
||||||
|
new(yaml, mode: mode).call
|
||||||
|
end
|
||||||
|
|
||||||
|
def initialize(yaml, mode:)
|
||||||
|
@yaml = yaml
|
||||||
|
@mode = mode.to_s
|
||||||
|
end
|
||||||
|
|
||||||
|
def call
|
||||||
|
validate_mode!
|
||||||
|
backup = load_backup
|
||||||
|
backup = migrate_backup(backup)
|
||||||
|
|
||||||
|
ActiveRecord::Base.transaction do
|
||||||
|
replace_app_data! if mode == "replace"
|
||||||
|
import_backup(backup)
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
private
|
||||||
|
|
||||||
|
attr_reader :yaml, :mode
|
||||||
|
|
||||||
|
def validate_mode!
|
||||||
|
return if MODES.include?(mode)
|
||||||
|
|
||||||
|
raise Error, "Choose a valid restore mode."
|
||||||
|
end
|
||||||
|
|
||||||
|
def load_backup
|
||||||
|
backup = YAML.safe_load(yaml, aliases: false)
|
||||||
|
raise Error, "Backup file is empty." unless backup.is_a?(Hash)
|
||||||
|
raise Error, "Backup format is not supported." unless backup["format"] == BackupExport::FORMAT
|
||||||
|
|
||||||
|
backup
|
||||||
|
rescue Psych::Exception
|
||||||
|
raise Error, "Backup file is not valid YAML."
|
||||||
|
end
|
||||||
|
|
||||||
|
def migrate_backup(backup)
|
||||||
|
version = backup["version"].to_i
|
||||||
|
return backup if version == SUPPORTED_VERSION
|
||||||
|
|
||||||
|
if version > SUPPORTED_VERSION
|
||||||
|
raise Error, "Backup version #{version} is newer than this application supports."
|
||||||
|
end
|
||||||
|
|
||||||
|
raise Error, "Backup version #{version} does not have an available migration path."
|
||||||
|
end
|
||||||
|
|
||||||
|
def replace_app_data!
|
||||||
|
UserSession.delete_all
|
||||||
|
FuelEntry.delete_all
|
||||||
|
MaintenanceEntry.delete_all
|
||||||
|
MaintenanceSchedule.delete_all
|
||||||
|
Vehicle.delete_all
|
||||||
|
User.delete_all
|
||||||
|
end
|
||||||
|
|
||||||
|
def import_backup(backup)
|
||||||
|
vehicles = backup.fetch("vehicles") { raise Error, "Backup is missing vehicles." }
|
||||||
|
raise Error, "Backup vehicles must be a list." unless vehicles.is_a?(Array)
|
||||||
|
|
||||||
|
vehicles.each do |vehicle_data|
|
||||||
|
import_vehicle(vehicle_data)
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
def import_vehicle(vehicle_data)
|
||||||
|
vehicle = find_or_initialize_vehicle(vehicle_data)
|
||||||
|
incoming_odometer = integer_value(vehicle_data.fetch("current_odometer"))
|
||||||
|
|
||||||
|
vehicle.assign_attributes(vehicle_attributes(vehicle_data).merge(current_odometer: incoming_odometer))
|
||||||
|
vehicle.save!
|
||||||
|
|
||||||
|
import_schedules(vehicle, array_value(vehicle_data, "maintenance_schedules"))
|
||||||
|
import_fuel_entries(vehicle, array_value(vehicle_data, "fuel_entries"))
|
||||||
|
import_maintenance_entries(vehicle, array_value(vehicle_data, "maintenance_entries"))
|
||||||
|
recalculate_odometer(vehicle, incoming_odometer)
|
||||||
|
rescue KeyError => error
|
||||||
|
raise Error, "Vehicle is missing required field #{error.key}."
|
||||||
|
rescue ActiveRecord::RecordInvalid => error
|
||||||
|
raise Error, error.record.errors.full_messages.to_sentence
|
||||||
|
end
|
||||||
|
|
||||||
|
def find_or_initialize_vehicle(vehicle_data)
|
||||||
|
vin = string_value(vehicle_data.fetch("vin"))
|
||||||
|
raise Error, "Vehicle VIN is required." if vin.blank?
|
||||||
|
|
||||||
|
Vehicle.find_or_initialize_by(vin: vin.upcase)
|
||||||
|
end
|
||||||
|
|
||||||
|
def vehicle_attributes(vehicle_data)
|
||||||
|
{
|
||||||
|
licence_plate: string_value(vehicle_data.fetch("licence_plate")),
|
||||||
|
make: string_value(vehicle_data.fetch("make")),
|
||||||
|
model: string_value(vehicle_data.fetch("model")),
|
||||||
|
year: integer_value(vehicle_data.fetch("year")),
|
||||||
|
color: string_value(vehicle_data.fetch("color")),
|
||||||
|
fuel_tank_size: decimal_value(vehicle_data.fetch("fuel_tank_size")),
|
||||||
|
active: boolean_value(vehicle_data.fetch("active"))
|
||||||
|
}
|
||||||
|
end
|
||||||
|
|
||||||
|
def import_schedules(vehicle, schedules)
|
||||||
|
schedules.each do |schedule_data|
|
||||||
|
schedule = vehicle.maintenance_schedules.find_or_initialize_by(
|
||||||
|
maintenance_type: string_value(schedule_data.fetch("maintenance_type"))
|
||||||
|
)
|
||||||
|
schedule.assign_attributes(
|
||||||
|
mileage_interval: integer_value(schedule_data.fetch("mileage_interval")),
|
||||||
|
time_interval: integer_value(schedule_data.fetch("time_interval")),
|
||||||
|
baseline_odometer: integer_value(schedule_data.fetch("baseline_odometer")),
|
||||||
|
baseline_date: date_value(schedule_data.fetch("baseline_date")),
|
||||||
|
active: boolean_value(schedule_data.fetch("active")),
|
||||||
|
last_status: optional_string_value(schedule_data["last_status"]),
|
||||||
|
last_status_changed_at: optional_time_value(schedule_data["last_status_changed_at"])
|
||||||
|
)
|
||||||
|
schedule.save!
|
||||||
|
end
|
||||||
|
rescue KeyError => error
|
||||||
|
raise Error, "Maintenance schedule is missing required field #{error.key}."
|
||||||
|
end
|
||||||
|
|
||||||
|
def import_fuel_entries(vehicle, entries)
|
||||||
|
entries.each do |entry_data|
|
||||||
|
user = import_user(entry_data.fetch("updated_by_user"))
|
||||||
|
next if fuel_entry_exists?(vehicle, entry_data, user)
|
||||||
|
|
||||||
|
FuelEntry.insert!({
|
||||||
|
vehicle_id: vehicle.id,
|
||||||
|
updated_by_user_id: user.id,
|
||||||
|
odometer: integer_value(entry_data.fetch("odometer")),
|
||||||
|
gallons_pumped: decimal_value(entry_data.fetch("gallons_pumped")),
|
||||||
|
price_paid: decimal_value(entry_data.fetch("price_paid")),
|
||||||
|
date: date_value(entry_data.fetch("date")),
|
||||||
|
created_at: Time.current,
|
||||||
|
updated_at: Time.current
|
||||||
|
})
|
||||||
|
end
|
||||||
|
rescue KeyError => error
|
||||||
|
raise Error, "Fuel entry is missing required field #{error.key}."
|
||||||
|
end
|
||||||
|
|
||||||
|
def import_maintenance_entries(vehicle, entries)
|
||||||
|
entries.each do |entry_data|
|
||||||
|
user = import_user(entry_data.fetch("updated_by_user"))
|
||||||
|
next if maintenance_entry_exists?(vehicle, entry_data, user)
|
||||||
|
|
||||||
|
MaintenanceEntry.insert!({
|
||||||
|
vehicle_id: vehicle.id,
|
||||||
|
updated_by_user_id: user.id,
|
||||||
|
name: string_value(entry_data.fetch("name")),
|
||||||
|
notes: string_value(entry_data.fetch("notes")),
|
||||||
|
odometer: integer_value(entry_data.fetch("odometer")),
|
||||||
|
cost: decimal_value(entry_data.fetch("cost")),
|
||||||
|
date: date_value(entry_data.fetch("date")),
|
||||||
|
created_at: Time.current,
|
||||||
|
updated_at: Time.current
|
||||||
|
})
|
||||||
|
end
|
||||||
|
rescue KeyError => error
|
||||||
|
raise Error, "Maintenance entry is missing required field #{error.key}."
|
||||||
|
end
|
||||||
|
|
||||||
|
def import_user(user_data)
|
||||||
|
raise Error, "Updated by user must be present." unless user_data.is_a?(Hash)
|
||||||
|
|
||||||
|
email = string_value(user_data.fetch("email")).downcase
|
||||||
|
user = User.find_or_initialize_by(email: email)
|
||||||
|
user.name = string_value(user_data.fetch("name"))
|
||||||
|
user.save!
|
||||||
|
user
|
||||||
|
rescue KeyError => error
|
||||||
|
raise Error, "User is missing required field #{error.key}."
|
||||||
|
end
|
||||||
|
|
||||||
|
def fuel_entry_exists?(vehicle, entry_data, user)
|
||||||
|
vehicle.fuel_entries.where(
|
||||||
|
updated_by_user: user,
|
||||||
|
odometer: integer_value(entry_data.fetch("odometer")),
|
||||||
|
gallons_pumped: decimal_value(entry_data.fetch("gallons_pumped")),
|
||||||
|
price_paid: decimal_value(entry_data.fetch("price_paid")),
|
||||||
|
date: date_value(entry_data.fetch("date"))
|
||||||
|
).exists?
|
||||||
|
end
|
||||||
|
|
||||||
|
def maintenance_entry_exists?(vehicle, entry_data, user)
|
||||||
|
vehicle.maintenance_entries.where(
|
||||||
|
updated_by_user: user,
|
||||||
|
name: string_value(entry_data.fetch("name")),
|
||||||
|
notes: string_value(entry_data.fetch("notes")),
|
||||||
|
odometer: integer_value(entry_data.fetch("odometer")),
|
||||||
|
cost: decimal_value(entry_data.fetch("cost")),
|
||||||
|
date: date_value(entry_data.fetch("date"))
|
||||||
|
).exists?
|
||||||
|
end
|
||||||
|
|
||||||
|
def recalculate_odometer(vehicle, incoming_odometer)
|
||||||
|
max_odometer = [
|
||||||
|
incoming_odometer,
|
||||||
|
vehicle.fuel_entries.maximum(:odometer),
|
||||||
|
vehicle.maintenance_entries.maximum(:odometer)
|
||||||
|
].compact.max
|
||||||
|
vehicle.update!(current_odometer: max_odometer)
|
||||||
|
end
|
||||||
|
|
||||||
|
def array_value(data, key)
|
||||||
|
value = data.fetch(key, [])
|
||||||
|
raise Error, "#{key.humanize} must be a list." unless value.is_a?(Array)
|
||||||
|
|
||||||
|
value
|
||||||
|
end
|
||||||
|
|
||||||
|
def string_value(value)
|
||||||
|
value.to_s.strip
|
||||||
|
end
|
||||||
|
|
||||||
|
def optional_string_value(value)
|
||||||
|
value.present? ? value.to_s : nil
|
||||||
|
end
|
||||||
|
|
||||||
|
def integer_value(value)
|
||||||
|
Integer(value)
|
||||||
|
rescue ArgumentError, TypeError
|
||||||
|
raise Error, "Expected an integer value."
|
||||||
|
end
|
||||||
|
|
||||||
|
def decimal_value(value)
|
||||||
|
BigDecimal(value.to_s)
|
||||||
|
rescue ArgumentError, TypeError
|
||||||
|
raise Error, "Expected a decimal value."
|
||||||
|
end
|
||||||
|
|
||||||
|
def date_value(value)
|
||||||
|
Date.iso8601(value.to_s)
|
||||||
|
rescue Date::Error, TypeError
|
||||||
|
raise Error, "Expected an ISO 8601 date."
|
||||||
|
end
|
||||||
|
|
||||||
|
def optional_time_value(value)
|
||||||
|
value.present? ? Time.zone.iso8601(value.to_s) : nil
|
||||||
|
rescue ArgumentError, TypeError
|
||||||
|
raise Error, "Expected an ISO 8601 time."
|
||||||
|
end
|
||||||
|
|
||||||
|
def boolean_value(value)
|
||||||
|
return value if value == true || value == false
|
||||||
|
|
||||||
|
raise Error, "Expected a boolean value."
|
||||||
|
end
|
||||||
|
end
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
<main class="page-shell">
|
||||||
|
<% if notice.present? %>
|
||||||
|
<p class="flash flash--notice"><%= notice %></p>
|
||||||
|
<% end %>
|
||||||
|
|
||||||
|
<% if flash[:alert].present? %>
|
||||||
|
<p class="flash flash--warning"><%= flash[:alert] %></p>
|
||||||
|
<% end %>
|
||||||
|
|
||||||
|
<p><%= link_to "Back to vehicles", vehicles_path, class: "back-link" %></p>
|
||||||
|
|
||||||
|
<header class="page-header">
|
||||||
|
<div>
|
||||||
|
<p class="eyebrow">Data portability</p>
|
||||||
|
<h1>Backup / Restore</h1>
|
||||||
|
</div>
|
||||||
|
</header>
|
||||||
|
|
||||||
|
<section class="dashboard-section dashboard-section--primary">
|
||||||
|
<h2>Download Backup</h2>
|
||||||
|
<p>Download a gzip-compressed YAML backup of vehicles, users, maintenance schedules, fuel entries, and maintenance entries.</p>
|
||||||
|
<p>Authentication data, access keys, and browser sessions are not included.</p>
|
||||||
|
<p><%= link_to "Download backup", download_backup_path, class: "button button--primary" %></p>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section class="dashboard-section">
|
||||||
|
<h2>Restore Backup</h2>
|
||||||
|
<p>Upload a `.yml.gz` backup exported from Car Tracker.</p>
|
||||||
|
|
||||||
|
<%= form_with url: restore_backup_path, multipart: true, class: "stacked-form" do |form| %>
|
||||||
|
<div class="field">
|
||||||
|
<%= form.label :backup_file, "Backup file" %>
|
||||||
|
<%= form.file_field :backup_file, accept: ".gz,.yml.gz,application/gzip", required: true %>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<fieldset class="field">
|
||||||
|
<legend>Restore mode</legend>
|
||||||
|
<label>
|
||||||
|
<%= radio_button_tag :mode, "merge", true %>
|
||||||
|
Merge data into this installation
|
||||||
|
</label>
|
||||||
|
<label>
|
||||||
|
<%= radio_button_tag :mode, "replace" %>
|
||||||
|
Replace all existing app data
|
||||||
|
</label>
|
||||||
|
</fieldset>
|
||||||
|
|
||||||
|
<p class="field-warning">Replace mode deletes existing vehicles, users, schedules, fuel entries, and maintenance entries before importing the backup.</p>
|
||||||
|
|
||||||
|
<div>
|
||||||
|
<%= form.submit "Restore backup", class: "button button--primary" %>
|
||||||
|
</div>
|
||||||
|
<% end %>
|
||||||
|
</section>
|
||||||
|
</main>
|
||||||
@@ -8,7 +8,10 @@
|
|||||||
<p class="eyebrow">Fleet dashboard</p>
|
<p class="eyebrow">Fleet dashboard</p>
|
||||||
<h1>Vehicles</h1>
|
<h1>Vehicles</h1>
|
||||||
</div>
|
</div>
|
||||||
<%= link_to "New vehicle", new_vehicle_path, class: "button button--primary" %>
|
<div class="action-row">
|
||||||
|
<%= link_to "Backup / Restore", backup_path, class: "button button--secondary" %>
|
||||||
|
<%= link_to "New vehicle", new_vehicle_path, class: "button button--primary" %>
|
||||||
|
</div>
|
||||||
</header>
|
</header>
|
||||||
|
|
||||||
<nav class="filter-nav" aria-label="Vehicle filters">
|
<nav class="filter-nav" aria-label="Vehicle filters">
|
||||||
|
|||||||
@@ -21,5 +21,10 @@ Rails.application.routes.draw do
|
|||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
|
resource :backup, only: :show do
|
||||||
|
get :download
|
||||||
|
post :restore
|
||||||
|
end
|
||||||
|
|
||||||
root "vehicles#index"
|
root "vehicles#index"
|
||||||
end
|
end
|
||||||
|
|||||||
@@ -0,0 +1,35 @@
|
|||||||
|
# Phase 008 Execution
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
- Add compressed YAML backup export and restore for portable application data.
|
||||||
|
- Support merge and replace restore modes.
|
||||||
|
- Exclude authentication and runtime data from backups.
|
||||||
|
|
||||||
|
## Changes
|
||||||
|
- Added `BackupExport` to produce versioned YAML containing vehicles, users referenced by entries, maintenance schedules, fuel entries, and maintenance entries.
|
||||||
|
- Added `BackupImport` to restore versioned YAML in merge or replace mode.
|
||||||
|
- Added gzip download and upload handling without adding gem dependencies.
|
||||||
|
- Added top-level backup routes and `BackupsController` actions for show, download, and restore.
|
||||||
|
- Added a backup/restore page with download, upload, merge, and replace controls.
|
||||||
|
- Added a `Backup / Restore` action to the vehicle dashboard.
|
||||||
|
- Added request specs for authentication, dashboard visibility, gzip YAML export, merge restore, duplicate prevention, replace restore, invalid gzip uploads, and unsupported backup versions.
|
||||||
|
|
||||||
|
## Decisions
|
||||||
|
- Backup files are gzip-compressed YAML files with a `.yml.gz` filename.
|
||||||
|
- Backups include app data only and exclude access keys and user sessions.
|
||||||
|
- Replace mode clears user sessions before replacing app data so users can be deleted without foreign-key failures.
|
||||||
|
- Replace mode preserves access keys because authentication configuration is outside backup scope.
|
||||||
|
- Merge mode updates matched users, vehicles, and maintenance schedules, and creates unmatched records.
|
||||||
|
- Users are matched by normalized email.
|
||||||
|
- Vehicles are matched by VIN.
|
||||||
|
- Maintenance schedules are matched by vehicle and maintenance type.
|
||||||
|
- Fuel and maintenance entries are deduplicated with natural keys using vehicle, user, date, odometer, and entry-specific values.
|
||||||
|
- Import uses direct inserts for historical entries so UI-specific validations do not block valid restored history.
|
||||||
|
- Vehicle current odometers are recalculated after import from incoming vehicle data and all fuel/maintenance entry odometers.
|
||||||
|
- Unknown newer versions and older versions without an explicit migration path are rejected.
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
- Passed: `bundle exec rspec spec/requests/backups_spec.rb`
|
||||||
|
- Passed: `bundle exec rspec`
|
||||||
|
- Passed: `bin/rubocop app/controllers/backups_controller.rb app/services/backup_export.rb app/services/backup_import.rb spec/requests/backups_spec.rb`
|
||||||
|
- Passed: `bin/ci`
|
||||||
@@ -0,0 +1,40 @@
|
|||||||
|
# Phase 008: Backup And Restore
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
Add backup and restore support for portable application data using compressed YAML files without adding new gem dependencies.
|
||||||
|
|
||||||
|
## Work
|
||||||
|
- Add a backup/restore page linked from the main vehicle dashboard.
|
||||||
|
- Export app data as a versioned YAML document compressed with gzip (`.yml.gz`).
|
||||||
|
- Include users, vehicles, maintenance schedules, fuel entries, and maintenance entries.
|
||||||
|
- Exclude authentication and runtime data, including access keys and user sessions.
|
||||||
|
- Restore uploaded backups in either merge mode or replace mode.
|
||||||
|
- Use portable references instead of raw database IDs so backups can be moved between installations.
|
||||||
|
- Support older backup versions only when an explicit migration path exists.
|
||||||
|
- Add request specs for export, merge restore, replace restore, invalid upload handling, and authentication.
|
||||||
|
|
||||||
|
## Decisions
|
||||||
|
- Backups use gzip-compressed YAML instead of zip archives because no extra gem dependency should be added.
|
||||||
|
- Any identified user may export or restore backups.
|
||||||
|
- Merge mode updates matched users, vehicles, and maintenance schedules, and creates unmatched records.
|
||||||
|
- Users are matched by normalized email.
|
||||||
|
- Vehicles are matched by VIN.
|
||||||
|
- Maintenance schedules are matched by vehicle and maintenance type.
|
||||||
|
- Fuel and maintenance entries use natural keys to avoid duplicate imports.
|
||||||
|
- Replace mode removes existing app data and imports the uploaded data inside one transaction.
|
||||||
|
- Restore recalculates vehicle odometers from imported/stored vehicle odometers and event histories.
|
||||||
|
|
||||||
|
## Deliverables
|
||||||
|
- Backup export/import services.
|
||||||
|
- Backup controller and routes.
|
||||||
|
- Backup/restore page and dashboard link.
|
||||||
|
- Request specs for backup and restore behavior.
|
||||||
|
- Phase execution notes.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
- Authenticated users can download a `.yml.gz` backup from the app.
|
||||||
|
- The backup contains app data only and excludes auth/session data.
|
||||||
|
- Authenticated users can restore by replacing all app data.
|
||||||
|
- Authenticated users can restore by merging portable records into existing app data.
|
||||||
|
- Invalid or unsupported uploads fail with a clear user-facing error.
|
||||||
|
- Backup and restore behavior is covered by request specs.
|
||||||
@@ -0,0 +1,234 @@
|
|||||||
|
require "rails_helper"
|
||||||
|
require "stringio"
|
||||||
|
require "zlib"
|
||||||
|
|
||||||
|
RSpec.describe "Backups" do
|
||||||
|
describe "unauthenticated access" do
|
||||||
|
it "redirects backup pages to identification" do
|
||||||
|
get backup_path
|
||||||
|
|
||||||
|
expect(response).to redirect_to(identify_path)
|
||||||
|
end
|
||||||
|
|
||||||
|
it "does not download backups" do
|
||||||
|
get download_backup_path
|
||||||
|
|
||||||
|
expect(response).to redirect_to(identify_path)
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
describe "GET /backup" do
|
||||||
|
before { identify_user }
|
||||||
|
|
||||||
|
it "renders the backup and restore page" do
|
||||||
|
get backup_path
|
||||||
|
|
||||||
|
expect(response).to have_http_status(:ok)
|
||||||
|
expect(response.body).to include("Backup / Restore")
|
||||||
|
expect(response.body).to include("Download backup")
|
||||||
|
expect(response.body).to include("Restore backup")
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
describe "GET /backup/download" do
|
||||||
|
before { identify_user }
|
||||||
|
|
||||||
|
it "downloads app data as gzip-compressed YAML" do
|
||||||
|
user = create(:user, name: "Driver", email: "driver@example.com")
|
||||||
|
vehicle = create(:vehicle, vin: "ABC123", licence_plate: "FLT1234")
|
||||||
|
create(:maintenance_schedule, vehicle: vehicle, maintenance_type: "Oil Change")
|
||||||
|
create(:fuel_entry, vehicle: vehicle, updated_by_user: user, odometer: 10_500)
|
||||||
|
create(:maintenance_entry, vehicle: vehicle, updated_by_user: user, name: "Oil Change", odometer: 10_600, ensure_matching_schedule: false)
|
||||||
|
AccessKey.current
|
||||||
|
UserSession.create_for!(user)
|
||||||
|
|
||||||
|
get download_backup_path
|
||||||
|
|
||||||
|
backup = YAML.safe_load(gunzip(response.body), aliases: false)
|
||||||
|
vehicle_data = backup.fetch("vehicles").first
|
||||||
|
|
||||||
|
expect(response).to have_http_status(:ok)
|
||||||
|
expect(response.media_type).to eq("application/gzip")
|
||||||
|
expect(response.headers.fetch("Content-Disposition")).to include(".yml.gz")
|
||||||
|
expect(backup.fetch("format")).to eq("car_tracker_backup")
|
||||||
|
expect(backup.fetch("version")).to eq(1)
|
||||||
|
expect(vehicle_data.fetch("vin")).to eq("ABC123")
|
||||||
|
expect(vehicle_data.fetch("fuel_entries").first.fetch("updated_by_user").fetch("email")).to eq("driver@example.com")
|
||||||
|
expect(gunzip(response.body)).not_to include("access_keys")
|
||||||
|
expect(gunzip(response.body)).not_to include("user_sessions")
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
describe "dashboard link" do
|
||||||
|
before { identify_user }
|
||||||
|
|
||||||
|
it "shows backup and restore on the main dashboard" do
|
||||||
|
get vehicles_path
|
||||||
|
|
||||||
|
expect(response.body).to include("Backup / Restore")
|
||||||
|
expect(response.body).to include(backup_path)
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
describe "POST /backup/restore" do
|
||||||
|
before { identify_user }
|
||||||
|
|
||||||
|
it "merges backup data into existing records" do
|
||||||
|
existing_user = create(:user, name: "Old Name", email: "driver@example.com")
|
||||||
|
existing_vehicle = create(:vehicle, vin: "ABC123", licence_plate: "OLD123", make: "Old", current_odometer: 1_000)
|
||||||
|
existing_schedule = create(:maintenance_schedule, vehicle: existing_vehicle, maintenance_type: "Oil Change", mileage_interval: 3_000)
|
||||||
|
|
||||||
|
expect do
|
||||||
|
post restore_backup_path, params: {
|
||||||
|
mode: "merge",
|
||||||
|
backup_file: uploaded_backup(backup_payload)
|
||||||
|
}
|
||||||
|
end.to change(FuelEntry, :count).by(1)
|
||||||
|
.and change(MaintenanceEntry, :count).by(1)
|
||||||
|
|
||||||
|
expect(response).to redirect_to(backup_path)
|
||||||
|
expect(existing_user.reload.name).to eq("Driver")
|
||||||
|
expect(existing_vehicle.reload.make).to eq("Ford")
|
||||||
|
expect(existing_vehicle.licence_plate).to eq("FLT1234")
|
||||||
|
expect(existing_vehicle.current_odometer).to eq(10_600)
|
||||||
|
expect(existing_schedule.reload.mileage_interval).to eq(5_000)
|
||||||
|
expect(Vehicle.count).to eq(1)
|
||||||
|
expect(User.count).to eq(2)
|
||||||
|
end
|
||||||
|
|
||||||
|
it "does not duplicate matching entries during merge" do
|
||||||
|
post restore_backup_path, params: { mode: "merge", backup_file: uploaded_backup(backup_payload) }
|
||||||
|
post restore_backup_path, params: { mode: "merge", backup_file: uploaded_backup(backup_payload) }
|
||||||
|
|
||||||
|
expect(Vehicle.count).to eq(1)
|
||||||
|
expect(FuelEntry.count).to eq(1)
|
||||||
|
expect(MaintenanceEntry.count).to eq(1)
|
||||||
|
end
|
||||||
|
|
||||||
|
it "replaces existing app data" do
|
||||||
|
create(:vehicle, vin: "OLDVIN", licence_plate: "OLD999")
|
||||||
|
create(:user, email: "old@example.com")
|
||||||
|
AccessKey.current
|
||||||
|
|
||||||
|
post restore_backup_path, params: {
|
||||||
|
mode: "replace",
|
||||||
|
backup_file: uploaded_backup(backup_payload)
|
||||||
|
}
|
||||||
|
|
||||||
|
expect(response).to redirect_to(backup_path)
|
||||||
|
expect(Vehicle.pluck(:vin)).to eq([ "ABC123" ])
|
||||||
|
expect(User.pluck(:email)).to contain_exactly("driver@example.com")
|
||||||
|
expect(AccessKey.count).to eq(1)
|
||||||
|
end
|
||||||
|
|
||||||
|
it "rejects invalid gzip uploads" do
|
||||||
|
expect do
|
||||||
|
post restore_backup_path, params: {
|
||||||
|
mode: "merge",
|
||||||
|
backup_file: uploaded_file("not gzip")
|
||||||
|
}
|
||||||
|
end.not_to change(Vehicle, :count)
|
||||||
|
|
||||||
|
expect(response).to redirect_to(backup_path)
|
||||||
|
expect(flash[:alert]).to include("gzip-compressed YAML")
|
||||||
|
end
|
||||||
|
|
||||||
|
it "rejects unsupported backup versions" do
|
||||||
|
payload = backup_payload.merge("version" => 0)
|
||||||
|
|
||||||
|
post restore_backup_path, params: {
|
||||||
|
mode: "merge",
|
||||||
|
backup_file: uploaded_backup(payload)
|
||||||
|
}
|
||||||
|
|
||||||
|
expect(response).to redirect_to(backup_path)
|
||||||
|
expect(flash[:alert]).to include("does not have an available migration path")
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
def backup_payload
|
||||||
|
{
|
||||||
|
"format" => "car_tracker_backup",
|
||||||
|
"version" => 1,
|
||||||
|
"exported_at" => Time.current.iso8601,
|
||||||
|
"vehicles" => [
|
||||||
|
{
|
||||||
|
"vin" => "ABC123",
|
||||||
|
"licence_plate" => "FLT1234",
|
||||||
|
"make" => "Ford",
|
||||||
|
"model" => "F-150",
|
||||||
|
"year" => Date.current.year,
|
||||||
|
"color" => "White",
|
||||||
|
"current_odometer" => 10_000,
|
||||||
|
"fuel_tank_size" => "26.0",
|
||||||
|
"active" => true,
|
||||||
|
"maintenance_schedules" => [
|
||||||
|
{
|
||||||
|
"maintenance_type" => "Oil Change",
|
||||||
|
"mileage_interval" => 5_000,
|
||||||
|
"time_interval" => 180,
|
||||||
|
"baseline_odometer" => 10_000,
|
||||||
|
"baseline_date" => Date.current.iso8601,
|
||||||
|
"active" => true,
|
||||||
|
"last_status" => nil,
|
||||||
|
"last_status_changed_at" => nil
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"fuel_entries" => [
|
||||||
|
{
|
||||||
|
"date" => Date.current.iso8601,
|
||||||
|
"odometer" => 10_500,
|
||||||
|
"gallons_pumped" => "18.25",
|
||||||
|
"price_paid" => "47.62",
|
||||||
|
"updated_by_user" => {
|
||||||
|
"name" => "Driver",
|
||||||
|
"email" => "driver@example.com"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"maintenance_entries" => [
|
||||||
|
{
|
||||||
|
"name" => "Oil Change",
|
||||||
|
"notes" => "Oil change performed.",
|
||||||
|
"date" => Date.current.iso8601,
|
||||||
|
"odometer" => 10_600,
|
||||||
|
"cost" => "89.95",
|
||||||
|
"updated_by_user" => {
|
||||||
|
"name" => "Driver",
|
||||||
|
"email" => "driver@example.com"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
end
|
||||||
|
|
||||||
|
def uploaded_backup(payload)
|
||||||
|
uploaded_file(gzip(payload.to_yaml))
|
||||||
|
end
|
||||||
|
|
||||||
|
def uploaded_file(content)
|
||||||
|
file = Tempfile.new([ "backup", ".yml.gz" ])
|
||||||
|
file.binmode
|
||||||
|
file.write(content)
|
||||||
|
file.rewind
|
||||||
|
Rack::Test::UploadedFile.new(file.path, "application/gzip")
|
||||||
|
end
|
||||||
|
|
||||||
|
def gzip(content)
|
||||||
|
buffer = StringIO.new
|
||||||
|
Zlib::GzipWriter.wrap(buffer) { |gzip| gzip.write(content) }
|
||||||
|
buffer.string
|
||||||
|
end
|
||||||
|
|
||||||
|
def gunzip(content)
|
||||||
|
Zlib::GzipReader.wrap(StringIO.new(content), &:read)
|
||||||
|
end
|
||||||
|
|
||||||
|
def identify_user(user = create(:user))
|
||||||
|
@identified_user = user
|
||||||
|
access_key = AccessKey.current
|
||||||
|
post session_path, params: { name: user.name, email: user.email, key: access_key.raw_key }
|
||||||
|
end
|
||||||
|
end
|
||||||
Reference in New Issue
Block a user