mirror of
https://github.com/rickbarrette/simple-aircraft-manager-rails.git
synced 2026-11-17 23:50:36 -05:00
REST API v1: tokens, read endpoints, squawks, webhooks
- Personal tokens (Profile → API tokens) act as their owner; integration tokens (Admin → Integrations) reach chosen aircraft and scopes, and their writes name the person they're for (SAM-On-Behalf-Of). Tokens are stored hashed, shown once, revocable, with last use recorded. - GET aircraft, components, due list, inspections, ADs, logbook entries and squawks; POST/PATCH squawks with external_ref links to the other system. - Idempotency-Key for safe retries, paging, JSON errors, rate limits. - Record history keeps the token with each change (in the hashed payload). - Webhooks (squawk created/updated/resolved, entry signed), HMAC-signed, retried, never sent to the server itself; deliveries listed for admins. - The outbound address check is shared by AirTrail and webhooks; reporting a squawk is announced the same way from the form and the API. - docs/guide/api.md: the API reference. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
ec0f43019f
commit
bffdea937c
45 files changed
+1577
-51
No files matched your search
@@ -0,0 +1,93 @@
|
||||
# Admin → Integrations: tokens for other systems (e.g. Redmine), limited to
|
||||
# chosen aircraft and scopes, each with an optional webhook (docs/api.md).
|
||||
# The token and webhook secret are shown once, right after they're made.
|
||||
class Admin::IntegrationsController < ApplicationController
|
||||
before_action :require_admin!
|
||||
before_action :set_integration, only: %i[show edit update destroy new_secret]
|
||||
|
||||
def index
|
||||
@integrations = ApiToken.integration.order(revoked_at: :desc, name: :asc).includes(:webhook_endpoints)
|
||||
end
|
||||
|
||||
def new
|
||||
@integration = ApiToken.new(kind: "integration", scopes: %w[read])
|
||||
@endpoint = WebhookEndpoint.new(events: [])
|
||||
end
|
||||
|
||||
def create
|
||||
@integration = ApiToken.new(integration_params.merge(kind: "integration", user: current_user))
|
||||
@endpoint = build_endpoint(@integration)
|
||||
ApiToken.transaction do
|
||||
@integration.save!
|
||||
@endpoint&.save!
|
||||
end
|
||||
@secret = @endpoint&.secret
|
||||
render :created
|
||||
rescue ActiveRecord::RecordInvalid
|
||||
@endpoint ||= WebhookEndpoint.new(events: [])
|
||||
render :new, status: :unprocessable_entity
|
||||
end
|
||||
|
||||
def show
|
||||
@endpoint = @integration.webhook_endpoints.first
|
||||
@deliveries = @endpoint ? @endpoint.deliveries.recent.limit(25) : []
|
||||
end
|
||||
|
||||
def edit
|
||||
@endpoint = @integration.webhook_endpoints.first || WebhookEndpoint.new(events: [])
|
||||
end
|
||||
|
||||
def update
|
||||
@endpoint = @integration.webhook_endpoints.first
|
||||
ApiToken.transaction do
|
||||
@integration.update!(integration_params)
|
||||
if webhook_params[:url].present?
|
||||
@endpoint ||= @integration.webhook_endpoints.new(secret: WebhookEndpoint.new_secret)
|
||||
@endpoint.update!(webhook_params)
|
||||
else
|
||||
@endpoint&.destroy!
|
||||
end
|
||||
end
|
||||
redirect_to admin_integration_path(@integration), notice: t("flash.admin_integrations.saved")
|
||||
rescue ActiveRecord::RecordInvalid
|
||||
@endpoint ||= WebhookEndpoint.new(events: [])
|
||||
render :edit, status: :unprocessable_entity
|
||||
end
|
||||
|
||||
# A new webhook secret, shown once.
|
||||
def new_secret
|
||||
@endpoint = @integration.webhook_endpoints.first or return redirect_to(admin_integration_path(@integration))
|
||||
@endpoint.update!(secret: WebhookEndpoint.new_secret)
|
||||
@secret = @endpoint.secret
|
||||
render :created
|
||||
end
|
||||
|
||||
def destroy
|
||||
@integration.revoke!
|
||||
@integration.webhook_endpoints.update_all(enabled: false)
|
||||
redirect_to admin_integrations_path, notice: t("flash.admin_integrations.revoked", name: @integration.name)
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
def set_integration = @integration = ApiToken.integration.find(params[:id])
|
||||
|
||||
def integration_params
|
||||
p = params.require(:api_token).permit(:name, scopes: [], aircraft_ids: [])
|
||||
p[:scopes] = Array(p[:scopes]) & ApiToken::SCOPES.keys
|
||||
p[:aircraft_ids] = Aircraft.where(id: Array(p[:aircraft_ids])).ids
|
||||
p
|
||||
end
|
||||
|
||||
def webhook_params
|
||||
p = params.fetch(:webhook, {}).permit(:url, :enabled, events: [])
|
||||
p[:events] = Array(p[:events]) & WebhookEndpoint::EVENTS.keys
|
||||
p[:enabled] = p[:enabled] != "0"
|
||||
p
|
||||
end
|
||||
|
||||
def build_endpoint(integration)
|
||||
return if webhook_params[:url].blank?
|
||||
integration.webhook_endpoints.new(webhook_params.merge(secret: WebhookEndpoint.new_secret))
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,49 @@
|
||||
module Api
|
||||
module V1
|
||||
# The fleet this token reaches, and each aircraft's own lists.
|
||||
class AircraftController < BaseController
|
||||
before_action -> { require_scope!(:read) }
|
||||
|
||||
def index
|
||||
render_page(aircraft_scope) { ApiPresenter.aircraft(_1) }
|
||||
end
|
||||
|
||||
def show
|
||||
render json: { data: ApiPresenter.aircraft(find_aircraft(params[:id])) }
|
||||
end
|
||||
|
||||
# The parts tree (?all=1 includes disposed parts).
|
||||
def components
|
||||
aircraft = find_aircraft(params[:id])
|
||||
scope = aircraft.components.includes(:component_type)
|
||||
scope = scope.where.not(status: "DISPOSED") unless params[:all].present?
|
||||
render_page(scope) { ApiPresenter.component(_1) }
|
||||
end
|
||||
|
||||
# Everything coming due, soonest first (hours projected to dates).
|
||||
def due
|
||||
aircraft = find_aircraft(params[:id])
|
||||
render json: { data: DueList.new(aircraft).items.map { ApiPresenter.due_item(_1) } }
|
||||
end
|
||||
|
||||
def inspections
|
||||
aircraft = find_aircraft(params[:id])
|
||||
render json: { data: Compliance.inspection_rows(aircraft).map { ApiPresenter.inspection(_1) } }
|
||||
end
|
||||
|
||||
def ads
|
||||
aircraft = find_aircraft(params[:id])
|
||||
render json: { data: Compliance.ad_rows(aircraft).map { ApiPresenter.ad(_1) } }
|
||||
end
|
||||
|
||||
# Logbook entries, oldest first (paged); ?log=AC|ENG|PROP|OTHER, ?signed=true|false.
|
||||
def logbook_entries
|
||||
aircraft = find_aircraft(params[:id])
|
||||
scope = aircraft.logbook_entries.includes(:signature)
|
||||
scope = scope.where(log_type: params[:log]) if params[:log].present?
|
||||
scope = params[:signed] == "true" ? scope.where.associated(:signature) : scope.where.missing(:signature) if params[:signed].present?
|
||||
render_page(scope) { ApiPresenter.logbook_entry(_1) }
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,123 @@
|
||||
# The REST API, version 1 (docs/api.md). JSON in and out; a token in
|
||||
# "Authorization: Bearer sam_…" instead of a browser session, so no cookies
|
||||
# and no CSRF tokens.
|
||||
#
|
||||
# A personal token acts as its owner. An integration token acts for the
|
||||
# person named in "SAM-On-Behalf-Of: <email>" (required for writes), and
|
||||
# reaches only its aircraft that person can also see.
|
||||
module Api
|
||||
module V1
|
||||
class BaseController < ActionController::API
|
||||
include RejectsNullBytes
|
||||
|
||||
MAX_PAGE = 200
|
||||
|
||||
before_action :authenticate
|
||||
rate_limit to: 600, within: 1.minute, by: -> { @api_token&.id || request.remote_ip },
|
||||
with: -> { render_error(:too_many_requests, "rate_limited", "Too many requests; slow down.") }
|
||||
around_action :idempotent, if: -> { request.post? || request.patch? || request.delete? }
|
||||
|
||||
rescue_from ActiveRecord::RecordNotFound do
|
||||
render_error(:not_found, "not_found", "Not found, or not available to this token.")
|
||||
end
|
||||
rescue_from ActionController::ParameterMissing, ActionDispatch::Http::Parameters::ParseError do |e|
|
||||
render_error(:bad_request, "bad_request", e.message.truncate(200))
|
||||
end
|
||||
rescue_from ActiveRecord::RecordInvalid do |e|
|
||||
render_invalid(e.record)
|
||||
end
|
||||
rescue_from ActiveSupport::MessageVerifier::InvalidSignature, ActiveModel::RangeError,
|
||||
ActiveRecord::NotNullViolation, ActiveRecord::InvalidForeignKey do
|
||||
render_error(:unprocessable_entity, "invalid", "Some values couldn't be saved.")
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
attr_reader :api_token
|
||||
|
||||
def acting_user = Current.api_user
|
||||
|
||||
def authenticate
|
||||
token = request.authorization.to_s[/\ABearer\s+(\S+)\z/i, 1]
|
||||
@api_token = ApiToken.authenticate(token)
|
||||
return render_error(:unauthorized, "unauthorized", "A valid API token is required.") unless @api_token
|
||||
|
||||
Current.api_token = @api_token
|
||||
Current.ip_address = request.remote_ip
|
||||
Current.api_user = @api_token.personal? ? @api_token.user : on_behalf_of
|
||||
@api_token.used!(request.remote_ip)
|
||||
end
|
||||
|
||||
# The person an integration is acting for, if it named one.
|
||||
def on_behalf_of
|
||||
email = request.headers["SAM-On-Behalf-Of"].to_s.strip.downcase.presence or return
|
||||
User.active.find_by(email_address: email) ||
|
||||
render_error(:unprocessable_entity, "unknown_user", "SAM-On-Behalf-Of doesn't match an active user.")
|
||||
end
|
||||
|
||||
def require_scope!(scope)
|
||||
return if api_token.allows?(scope)
|
||||
render_error(:forbidden, "missing_scope", "This token doesn't have the #{scope} scope.")
|
||||
end
|
||||
|
||||
# Writes always name a person, so the record history shows who.
|
||||
def require_person!
|
||||
return if acting_user
|
||||
render_error(:unprocessable_entity, "on_behalf_of_required", "Writes with an integration token need SAM-On-Behalf-Of.")
|
||||
end
|
||||
|
||||
def aircraft_scope = api_token.aircraft_scope(acting_user)
|
||||
|
||||
def find_aircraft(id = params[:aircraft_id]) = aircraft_scope.find(id)
|
||||
|
||||
def role_on(aircraft) = acting_user&.role_for(aircraft)
|
||||
def owner_of?(aircraft) = role_on(aircraft).in?(%w[admin owner])
|
||||
|
||||
# ?limit= (1–200, default 50), ?after=<id> to continue, ?updated_since=<ISO time>.
|
||||
def paginate(scope)
|
||||
limit = params.fetch(:limit, 50).to_i.clamp(1, MAX_PAGE)
|
||||
scope = scope.where(scope.arel_table[:id].gt(params[:after].to_i)) if params[:after].present?
|
||||
if params[:updated_since].present?
|
||||
since = Time.iso8601(params[:updated_since].to_s) rescue (raise ActionController::BadRequest, "updated_since must be an ISO 8601 time")
|
||||
scope = scope.where(scope.arel_table[:updated_at].gteq(since))
|
||||
end
|
||||
records = scope.reorder(:id).limit(limit + 1).to_a
|
||||
more = records.size > limit
|
||||
records = records.first(limit)
|
||||
[ records, (records.last.id if more) ]
|
||||
end
|
||||
|
||||
def render_page(scope, &present)
|
||||
records, next_after = paginate(scope)
|
||||
render json: { data: records.map(&present), next_after: next_after }
|
||||
end
|
||||
|
||||
def render_error(status, code, message, fields: nil)
|
||||
render json: { error: { code: code, message: message, fields: fields }.compact }, status: status
|
||||
end
|
||||
|
||||
def render_invalid(record)
|
||||
render_error(:unprocessable_entity, "invalid", record.errors.full_messages.to_sentence, fields: record.errors.to_hash)
|
||||
end
|
||||
|
||||
# The same Idempotency-Key again (a retry) gets the first answer; the
|
||||
# same key with a different request is a conflict.
|
||||
def idempotent
|
||||
key = request.headers["Idempotency-Key"].to_s.strip
|
||||
return yield if key.empty? || api_token.nil?
|
||||
return render_error(:bad_request, "bad_request", "Idempotency-Key is too long.") if key.length > 100
|
||||
|
||||
digest = OpenSSL::Digest::SHA256.hexdigest([ request.method, request.path, request.raw_post ].join("\n"))
|
||||
if (seen = api_token.idempotency_keys.find_by(key: key))
|
||||
return render_error(:conflict, "idempotency_conflict", "This Idempotency-Key was used for a different request.") if seen.request_digest != digest
|
||||
response.headers["Idempotent-Replay"] = "true"
|
||||
return render(json: seen.response_body, status: seen.response_status)
|
||||
end
|
||||
yield
|
||||
return if response.status >= 500
|
||||
api_token.idempotency_keys.create(key: key, request_digest: digest, response_status: response.status,
|
||||
response_body: response.body, created_at: Time.current)
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,16 @@
|
||||
module Api
|
||||
module V1
|
||||
# What this token is and who it's acting as: a quick check for a new integration.
|
||||
class MeController < BaseController
|
||||
def show
|
||||
render json: { data: {
|
||||
token: { name: api_token.name, kind: api_token.kind, hint: api_token.token_hint, scopes: api_token.scopes,
|
||||
aircraft_ids: (api_token.aircraft_ids if api_token.integration?) }.compact,
|
||||
acting_as: acting_user && { id: acting_user.id, name: acting_user.display_name, email: acting_user.email_address },
|
||||
aircraft_ids: aircraft_scope.ids,
|
||||
api_version: "v1", app_version: Rails.root.join("VERSION").read.strip
|
||||
} }
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,66 @@
|
||||
module Api
|
||||
module V1
|
||||
# Squawks: list and report on an aircraft; find by external_ref; update.
|
||||
# Resolving happens through a signed logbook entry, not here.
|
||||
class SquawksController < BaseController
|
||||
before_action -> { require_scope!(:read) }, only: %i[index show lookup]
|
||||
before_action -> { require_scope!("squawks:write") }, :require_person!, only: %i[create update]
|
||||
|
||||
# GET /aircraft/:aircraft_id/squawks?status=open|resolved|all (default open)
|
||||
def index
|
||||
scope = find_aircraft.squawks.includes(:reported_by).with_attached_attachments
|
||||
scope = case params.fetch(:status, "open")
|
||||
when "open" then scope.active
|
||||
when "resolved" then scope.resolved
|
||||
else scope
|
||||
end
|
||||
render_page(scope) { ApiPresenter.squawk(_1) }
|
||||
end
|
||||
|
||||
# GET /squawks?external_ref=redmine:issue:4512
|
||||
def lookup
|
||||
ref = params.require(:external_ref)
|
||||
scope = Squawk.where(aircraft: aircraft_scope, external_ref: ref).includes(:reported_by).with_attached_attachments
|
||||
render json: { data: scope.map { ApiPresenter.squawk(_1) } }
|
||||
end
|
||||
|
||||
def show
|
||||
render json: { data: ApiPresenter.squawk(find_squawk) }
|
||||
end
|
||||
|
||||
# POST /aircraft/:aircraft_id/squawks
|
||||
def create
|
||||
aircraft = find_aircraft
|
||||
squawk = aircraft.squawks.new(create_params.merge(reported_by: acting_user, resolved: false))
|
||||
squawk.component_id = nil unless aircraft.components.exists?(id: squawk.component_id)
|
||||
squawk.save!
|
||||
SquawkReported.call(squawk, by: acting_user)
|
||||
render json: { data: ApiPresenter.squawk(squawk) }, status: :created
|
||||
end
|
||||
|
||||
# PATCH /squawks/:id: external_ref by anyone who may write; the rest
|
||||
# (issue, priority, component, notes) by the aircraft's owners, as in the app.
|
||||
def update
|
||||
squawk = find_squawk
|
||||
return render_error(:unprocessable_entity, "resolved", "A resolved squawk can't be changed.") if squawk.resolved?
|
||||
attrs = params.require(:squawk).permit(:external_ref, :issue_reported, :priority, :component_id, :notes)
|
||||
if (attrs.keys - %w[external_ref]).any? && !owner_of?(squawk.aircraft)
|
||||
return render_error(:forbidden, "owners_only", "Only the aircraft's owners can change a squawk's details.")
|
||||
end
|
||||
attrs[:component_id] = nil if attrs.key?(:component_id) && !squawk.aircraft.components.exists?(id: attrs[:component_id])
|
||||
squawk.update!(attrs)
|
||||
render json: { data: ApiPresenter.squawk(squawk) }
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
def find_squawk = Squawk.where(aircraft: aircraft_scope).find(params[:id])
|
||||
|
||||
def create_params
|
||||
params.require(:squawk).permit(:issue_reported, :priority, :component_id, :external_ref).tap do |p|
|
||||
p[:priority] = p.fetch(:priority, 2).to_i
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,19 @@
|
||||
# Profile → API tokens: personal tokens for the REST API (docs/api.md). The
|
||||
# token is shown once, on the page right after it's made (not kept in the
|
||||
# flash or anywhere else).
|
||||
class ApiTokensController < ApplicationController
|
||||
def create
|
||||
@token = current_user.api_tokens.new(name: params.dig(:api_token, :name), kind: "personal",
|
||||
scopes: Array(params.dig(:api_token, :scopes)) & ApiToken::SCOPES.keys)
|
||||
if @token.save
|
||||
render :created
|
||||
else
|
||||
redirect_to edit_profile_path(anchor: "api"), alert: @token.errors.full_messages.to_sentence
|
||||
end
|
||||
end
|
||||
|
||||
def destroy
|
||||
current_user.api_tokens.personal.active.find(params[:id]).revoke!
|
||||
redirect_to edit_profile_path(anchor: "api"), notice: t("flash.api_tokens.revoked")
|
||||
end
|
||||
end
|
||||
@@ -4,8 +4,8 @@ class ApplicationController < ActionController::Base
|
||||
include TimeZones
|
||||
allow_browser versions: :modern
|
||||
|
||||
include RejectsNullBytes
|
||||
prepend_before_action :redirect_to_setup
|
||||
prepend_before_action :reject_null_bytes
|
||||
before_action { Current.ip_address = request.remote_ip } # for record history
|
||||
helper_method :current_user
|
||||
|
||||
@@ -36,20 +36,6 @@ class ApplicationController < ActionController::Base
|
||||
|
||||
private
|
||||
|
||||
# No form sends a null byte; some libraries (password hashing, file paths)
|
||||
# raise on one, so refuse the request up front.
|
||||
def reject_null_bytes
|
||||
head :bad_request if contains_null_byte?(request.params)
|
||||
end
|
||||
|
||||
def contains_null_byte?(value)
|
||||
case value
|
||||
when String then value.include?("\0")
|
||||
when Hash then value.any? { |k, v| contains_null_byte?(k) || contains_null_byte?(v) }
|
||||
when Array then value.any? { contains_null_byte?(_1) }
|
||||
else false
|
||||
end
|
||||
end
|
||||
|
||||
def current_user = Current.user
|
||||
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
# No form or API client sends a null byte; some libraries (password hashing,
|
||||
# file paths) raise on one, so such requests are refused up front.
|
||||
module RejectsNullBytes
|
||||
extend ActiveSupport::Concern
|
||||
|
||||
included { prepend_before_action :reject_null_bytes }
|
||||
|
||||
private
|
||||
|
||||
def reject_null_bytes
|
||||
head :bad_request if contains_null_byte?(request.params)
|
||||
end
|
||||
|
||||
def contains_null_byte?(value)
|
||||
case value
|
||||
when String then value.include?("\0")
|
||||
when Hash then value.any? { |k, v| contains_null_byte?(k) || contains_null_byte?(v) }
|
||||
when Array then value.any? { contains_null_byte?(_1) }
|
||||
else false
|
||||
end
|
||||
end
|
||||
end
|
||||
@@ -21,11 +21,7 @@ class SquawksController < ApplicationController
|
||||
end
|
||||
@squawk = @aircraft.squawks.new(squawk_params.merge(reported_by: current_user))
|
||||
if @squawk.save
|
||||
log_event("squawk", t("flash.squawks.squawk_reported_2", priority_label: @squawk.priority_label), notes: @squawk.issue_reported.truncate(200))
|
||||
if @squawk.grounding?
|
||||
PushNotifier.notify(@aircraft.users.merge(User.active).where.not(id: current_user.id), :grounding_squawk, path: aircraft_squawks_path(@aircraft),
|
||||
tag: "squawk-#{@squawk.id}", tail: @aircraft.tail_number, issue: @squawk.issue_reported.truncate(120))
|
||||
end
|
||||
SquawkReported.call(@squawk, by: current_user)
|
||||
redirect_to aircraft_squawks_path(@aircraft), notice: t("flash.squawks.squawk_reported")
|
||||
else
|
||||
render :new, status: :unprocessable_entity
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
require "net/http"
|
||||
|
||||
# Posts one webhook delivery. The body is signed so the receiver can check
|
||||
# it came from here and wasn't replayed:
|
||||
# SAM-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "<t>.<body>" with the endpoint's secret>
|
||||
# Anything but a 2xx answer is retried with growing waits, then marked failed.
|
||||
class WebhookDeliveryJob < ApplicationJob
|
||||
queue_as :default
|
||||
ATTEMPTS = 8
|
||||
|
||||
class Failed < StandardError; end
|
||||
|
||||
retry_on Failed, wait: :polynomially_longer, attempts: ATTEMPTS do |job, error|
|
||||
WebhookDelivery.find_by(id: job.arguments.first)&.update!(status: "failed", last_error: error.message.truncate(250))
|
||||
end
|
||||
|
||||
def perform(delivery_id)
|
||||
delivery = WebhookDelivery.includes(:webhook_endpoint).find_by(id: delivery_id) or return
|
||||
return if delivery.status == "delivered"
|
||||
endpoint = delivery.webhook_endpoint
|
||||
delivery.increment!(:attempts)
|
||||
response = post(endpoint, delivery)
|
||||
if response.code.to_i.between?(200, 299)
|
||||
delivery.update!(status: "delivered", response_status: response.code.to_i, delivered_at: Time.current, last_error: nil)
|
||||
else
|
||||
delivery.update!(response_status: response.code.to_i, last_error: "HTTP #{response.code}")
|
||||
raise Failed, "HTTP #{response.code}"
|
||||
end
|
||||
rescue OutboundAddress::Blocked => e
|
||||
# Pointed at an address the server won't send to: retrying won't help.
|
||||
delivery.update!(status: "failed", last_error: "blocked address (#{e.reason})")
|
||||
rescue Timeout::Error, SocketError, SystemCallError, OpenSSL::SSL::SSLError, EOFError, IOError => e
|
||||
delivery.update!(last_error: "#{e.class.name.demodulize}: #{e.message}".truncate(250))
|
||||
raise Failed, e.message
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
def post(endpoint, delivery)
|
||||
uri = URI.parse(endpoint.url)
|
||||
timestamp = Time.current.to_i
|
||||
signature = OpenSSL::HMAC.hexdigest("SHA256", endpoint.secret, "#{timestamp}.#{delivery.payload}")
|
||||
req = Net::HTTP::Post.new(uri)
|
||||
req["Content-Type"] = "application/json"
|
||||
req["User-Agent"] = "SimpleAircraftManager-Webhooks"
|
||||
req["SAM-Event"] = delivery.event
|
||||
req["SAM-Delivery"] = delivery.id.to_s
|
||||
req["SAM-Signature"] = "t=#{timestamp},v1=#{signature}"
|
||||
req.body = delivery.payload
|
||||
http = Net::HTTP.new(uri.host, uri.port)
|
||||
http.ipaddr = OutboundAddress.resolve!(uri.host, allow_private: true) # set up by an admin: the private network is fine
|
||||
http.use_ssl = uri.scheme == "https"
|
||||
http.open_timeout = 5
|
||||
http.read_timeout = 10
|
||||
http.start { _1.request(req) }
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,9 @@
|
||||
# A write sent with an Idempotency-Key header, and the answer it got: the
|
||||
# same key again (a retry) gets the same answer instead of a second record.
|
||||
class ApiIdempotencyKey < ApplicationRecord
|
||||
KEEP_FOR = 24.hours
|
||||
|
||||
belongs_to :api_token
|
||||
|
||||
def self.purge_old = where(created_at: ...KEEP_FOR.ago).delete_all
|
||||
end
|
||||
@@ -0,0 +1,80 @@
|
||||
# A key for the REST API (docs/api.md). Only its SHA-256 digest is kept; the
|
||||
# token itself is shown once, when it's made.
|
||||
#
|
||||
# personal: acts as its owner, with exactly their aircraft and role.
|
||||
# integration: made by an admin for another system (e.g. Redmine), limited to
|
||||
# chosen aircraft and scopes. Its writes name the person they're
|
||||
# for (SAM-On-Behalf-Of), so the record history always shows who.
|
||||
class ApiToken < ApplicationRecord
|
||||
KINDS = %w[personal integration].freeze
|
||||
SCOPES = LabelSet.new("api_token.scopes", %w[read squawks:write])
|
||||
PREFIX = "sam_"
|
||||
|
||||
belongs_to :user
|
||||
has_many :webhook_endpoints, dependent: :destroy
|
||||
has_many :idempotency_keys, class_name: "ApiIdempotencyKey", dependent: :delete_all
|
||||
|
||||
attr_reader :token # the plain token, only right after create
|
||||
|
||||
normalizes :name, with: ->(n) { n.to_s.strip }
|
||||
validates :name, presence: true, length: { maximum: 80 }
|
||||
validates :kind, inclusion: { in: KINDS }
|
||||
validate :scopes_known
|
||||
validate :integration_made_by_admin, on: :create
|
||||
|
||||
before_validation :generate, on: :create
|
||||
|
||||
scope :active, -> { where(revoked_at: nil) }
|
||||
scope :personal, -> { where(kind: "personal") }
|
||||
scope :integration, -> { where(kind: "integration") }
|
||||
|
||||
def self.digest(token) = OpenSSL::Digest::SHA256.hexdigest(token.to_s)
|
||||
|
||||
# The token for this string, if it's in use (and its owner is too).
|
||||
def self.authenticate(token)
|
||||
return unless token.to_s.start_with?(PREFIX)
|
||||
found = active.includes(:user).find_by(token_digest: digest(token))
|
||||
found if found && (found.integration? || !found.user.disabled?)
|
||||
end
|
||||
|
||||
def personal? = kind == "personal"
|
||||
def integration? = kind == "integration"
|
||||
def revoked? = revoked_at.present?
|
||||
def revoke! = update!(revoked_at: Time.current)
|
||||
def allows?(scope) = scopes.include?(scope.to_s)
|
||||
|
||||
# The aircraft this token reaches, acting for `user` (who must also have
|
||||
# access, for an integration acting on someone's behalf).
|
||||
def aircraft_scope(acting_user)
|
||||
if personal?
|
||||
user.accessible_aircraft
|
||||
else
|
||||
reachable = Aircraft.where(id: Array(aircraft_ids))
|
||||
acting_user ? reachable.where(id: acting_user.accessible_aircraft.select(:id)) : reachable
|
||||
end
|
||||
end
|
||||
|
||||
# Last use, at most once a minute (no write per request).
|
||||
def used!(ip)
|
||||
return if last_used_at && last_used_at > 1.minute.ago && last_used_ip == ip
|
||||
update_columns(last_used_at: Time.current, last_used_ip: ip)
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
def generate
|
||||
@token = "#{PREFIX}#{SecureRandom.base58(40)}"
|
||||
self.token_digest = self.class.digest(@token)
|
||||
self.token_hint = @token.first(PREFIX.length + 6)
|
||||
self.scopes = Array(scopes).map(&:to_s).compact_blank.uniq
|
||||
end
|
||||
|
||||
def scopes_known
|
||||
errors.add(:scopes, :blank) if scopes.blank?
|
||||
errors.add(:scopes, :inclusion) if (Array(scopes) - SCOPES.keys).any?
|
||||
end
|
||||
|
||||
def integration_made_by_admin
|
||||
errors.add(:kind, :admins_only) if integration? && !user&.admin?
|
||||
end
|
||||
end
|
||||
@@ -1,4 +1,7 @@
|
||||
class Current < ActiveSupport::CurrentAttributes
|
||||
attribute :session, :ip_address
|
||||
delegate :user, to: :session, allow_nil: true
|
||||
# api_token / api_user: an API request (see Api::V1::BaseController), which
|
||||
# acts as a person without a browser session.
|
||||
attribute :session, :ip_address, :api_token, :api_user
|
||||
|
||||
def user = api_user || session&.user
|
||||
end
|
||||
@@ -18,6 +18,12 @@ class EntrySignature < ApplicationRecord
|
||||
validates :auth_method, inclusion: { in: AUTH_METHODS.keys + [ "imported" ] }
|
||||
validates :logbook_entry_id, uniqueness: true
|
||||
before_create { self.seal ||= compute_seal unless imported? }
|
||||
# Integrations hear about it (webhooks); not for signatures carried over by an import.
|
||||
after_create_commit do
|
||||
next if imported?
|
||||
entry = logbook_entry
|
||||
Webhooks.publish("entry.signed", aircraft: entry.aircraft, data: ApiPresenter.logbook_entry(entry))
|
||||
end
|
||||
before_update { throw :abort } # signatures are permanent (2.1.2.7)
|
||||
before_destroy { throw :abort unless destroyed_by_association }
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
class HelpGuide
|
||||
DIR = Rails.root.join("docs/guide")
|
||||
ORDER = %w[README getting-started profile aircraft flights squawks oil-and-fuel components logbook records
|
||||
inspections ads documents major-records sharing administration disclaimer changelog].freeze
|
||||
inspections ads documents major-records sharing administration api disclaimer changelog].freeze
|
||||
OPTIONS = {
|
||||
parse: { smart: true },
|
||||
render: { hardbreaks: false, unsafe: false },
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
# editing a version breaks the chain and the nightly check reports it.
|
||||
class RecordVersion < ApplicationRecord
|
||||
belongs_to :user, optional: true
|
||||
belongs_to :api_token, optional: true
|
||||
|
||||
scope :chronological, -> { order(:id) }
|
||||
|
||||
@@ -15,10 +16,12 @@ class RecordVersion < ApplicationRecord
|
||||
def self.append!(item:, aircraft_id:, event:, changes:)
|
||||
now = Time.current
|
||||
payload = { "item_type" => item.class.name, "item_id" => item.id, "event" => event, "changes" => changes,
|
||||
"user_id" => Current.user&.id, "at" => now.utc.iso8601(6) }.to_json
|
||||
"user_id" => Current.user&.id, "at" => now.utc.iso8601(6) }
|
||||
payload["api_token_id"] = Current.api_token.id if Current.api_token # made through the API (part of the hashed payload)
|
||||
payload = payload.to_json
|
||||
prev = where(aircraft_id: aircraft_id).order(:id).last&.chain_hash
|
||||
create!(aircraft_id: aircraft_id, item_type: item.class.name, item_id: item.id, event: event, user_id: Current.user&.id,
|
||||
ip_address: Current.ip_address, payload: payload, prev_hash: prev, chain_hash: digest(prev, payload), created_at: now)
|
||||
ip_address: Current.ip_address, api_token_id: Current.api_token&.id, payload: payload, prev_hash: prev, chain_hash: digest(prev, payload), created_at: now)
|
||||
end
|
||||
|
||||
def changes_hash = JSON.parse(payload)["changes"]
|
||||
|
||||
@@ -11,6 +11,15 @@ class Squawk < ApplicationRecord
|
||||
belongs_to :logbook_entry, optional: true
|
||||
has_many_attached :attachments
|
||||
|
||||
# Integrations hear about squawks (webhooks), once the change is saved.
|
||||
after_create_commit { Webhooks.publish("squawk.created", aircraft: aircraft, data: ApiPresenter.squawk(self)) }
|
||||
after_update_commit do
|
||||
next if (saved_changes.keys - %w[updated_at]).empty?
|
||||
event = saved_change_to_resolved? && resolved? ? "squawk.resolved" : "squawk.updated"
|
||||
Webhooks.publish(event, aircraft: aircraft, data: ApiPresenter.squawk(self))
|
||||
end
|
||||
|
||||
normalizes :external_ref, with: ->(r) { r.to_s.strip.first(200).presence }
|
||||
validates :priority, inclusion: { in: PRIORITIES.keys }
|
||||
validates :issue_reported, presence: true
|
||||
validates_uploads :attachments
|
||||
|
||||
@@ -3,6 +3,7 @@ class User < ApplicationRecord
|
||||
has_many :sessions, dependent: :destroy
|
||||
has_many :aircraft_roles, dependent: :destroy
|
||||
has_many :push_subscriptions, dependent: :delete_all
|
||||
has_many :api_tokens, dependent: :destroy
|
||||
|
||||
normalizes :time_zone, with: ->(z) { z.strip.presence }
|
||||
validates :time_zone, inclusion: { in: ->(_) { ActiveSupport::TimeZone.all.map(&:name) } }, allow_nil: true
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# One event sent (or being sent) to a webhook endpoint; the recent ones are
|
||||
# listed for the admin, with the answer the other system gave.
|
||||
class WebhookDelivery < ApplicationRecord
|
||||
KEEP_FOR = 30.days
|
||||
|
||||
belongs_to :webhook_endpoint
|
||||
|
||||
scope :recent, -> { order(created_at: :desc) }
|
||||
|
||||
def self.purge_old = where(created_at: ...KEEP_FOR.ago).delete_all
|
||||
end
|
||||
@@ -0,0 +1,28 @@
|
||||
# Where an integration wants to hear about changes (squawks, signed entries):
|
||||
# SAM posts JSON there, signed with the shared secret (see WebhookDeliveryJob).
|
||||
class WebhookEndpoint < ApplicationRecord
|
||||
EVENTS = LabelSet.new("webhook_endpoint.events", %w[squawk.created squawk.updated squawk.resolved entry.signed])
|
||||
|
||||
belongs_to :api_token
|
||||
has_many :deliveries, class_name: "WebhookDelivery", dependent: :delete_all
|
||||
|
||||
encrypts :secret
|
||||
|
||||
normalizes :url, with: ->(u) { u.to_s.strip }
|
||||
validates :url, presence: true, format: { with: %r{\Ahttps?://[^\s/]+(:\d+)?(/\S*)?\z}i }
|
||||
validates :secret, presence: true, length: { minimum: 16 }
|
||||
validate :events_known
|
||||
|
||||
scope :enabled, -> { where(enabled: true) }
|
||||
|
||||
def self.new_secret = SecureRandom.hex(32)
|
||||
|
||||
def subscribed?(event) = events.include?(event.to_s)
|
||||
|
||||
private
|
||||
|
||||
def events_known
|
||||
errors.add(:events, :blank) if events.blank?
|
||||
errors.add(:events, :inclusion) if (Array(events) - EVENTS.keys).any?
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,69 @@
|
||||
# What the API and webhooks send for each kind of record (docs/api.md).
|
||||
# Times are ISO 8601 UTC, hours decimals, codes rather than translated labels.
|
||||
module ApiPresenter
|
||||
module_function
|
||||
|
||||
def aircraft(a)
|
||||
aw = a.airworthiness
|
||||
{ id: a.id, tail_number: a.tail_number, make: a.make, model: a.model, serial_number: a.serial_number,
|
||||
icao_type: a.icao_type, status: a.status,
|
||||
airworthiness: { status: aw.status, issues: aw.issues.map { { category: _1.category, severity: _1.severity, title: _1.title } } },
|
||||
time_basis: a.time_basis, hours: dec(a.current_hours), tach: dec(a.tach_time), hobbs: dec(a.hobbs_time),
|
||||
updated_at: time(a.updated_at) }
|
||||
end
|
||||
|
||||
def component(c)
|
||||
{ id: c.id, aircraft_id: c.aircraft_id, parent_id: c.parent_component_id, type: c.component_type&.name,
|
||||
manufacturer: c.manufacturer, model: c.model, serial_number: c.serial_number.presence,
|
||||
location: c.install_location.presence, status: c.status, date_in_service: c.date_in_service&.iso8601,
|
||||
hours_in_service: dec(c.hours_in_service), hours_since_overhaul: dec(c.hours_since_overhaul),
|
||||
overhaul_date: c.overhaul_date&.iso8601, overhaul_kind: c.overhaul_kind.presence,
|
||||
tbo: { hours: c.tbo_hours, days: c.tbo_days, months: c.tbo_months, on_condition: c.on_condition, critical: c.tbo_critical }.compact,
|
||||
replacement: { hours: c.replacement_hours, days: c.replacement_days, months: c.replacement_months, critical: c.replacement_critical }.compact,
|
||||
expires_on: c.expires_on&.iso8601, updated_at: time(c.updated_at) }
|
||||
end
|
||||
|
||||
def due_item(i)
|
||||
{ key: i.key, title: i.title, kind: i.kind, due_date: i.date.iso8601, projected: i.projected,
|
||||
due_hours: dec(i.due_hours), overdue: i.overdue? }
|
||||
end
|
||||
|
||||
def squawk(s)
|
||||
{ id: s.id, aircraft_id: s.aircraft_id, component_id: s.component_id, issue_reported: s.issue_reported,
|
||||
priority: s.priority, grounding: s.grounding?, deferred: s.deferred?, resolved: !!s.resolved,
|
||||
resolved_at: time(s.resolved_at), notes: s.notes.presence, logbook_entry_id: s.logbook_entry_id,
|
||||
reported_by: s.reported_by&.display_name, external_ref: s.external_ref,
|
||||
attachments: s.attachments.map { _1.filename.to_s },
|
||||
created_at: time(s.created_at), updated_at: time(s.updated_at) }
|
||||
end
|
||||
|
||||
def logbook_entry(e)
|
||||
sig = e.signature
|
||||
{ id: e.id, aircraft_id: e.aircraft_id, component_id: e.component_id, log: e.log_type, entry_type: e.entry_type,
|
||||
date: e.date.iso8601, text: e.text, aircraft_hours: dec(e.aircraft_hours_at_entry),
|
||||
inspection_result: e.inspection_result.presence, verified: e.verified, superseded: e.superseded_at.present?,
|
||||
signed: sig.present?, signature: sig && signature(sig),
|
||||
signoff: sig ? nil : { person: e.signoff_person.presence, certificate_type: e.signoff_certificate_type.presence,
|
||||
certificate_number: e.signoff_certificate_number.presence }.compact.presence,
|
||||
created_at: time(e.created_at), updated_at: time(e.updated_at) }
|
||||
end
|
||||
|
||||
def signature(sig)
|
||||
{ signer_name: sig.signer_name, certificate_kind: sig.certificate_kind, certificate_number: sig.certificate_number,
|
||||
signed_at: time(sig.signed_at) }
|
||||
end
|
||||
|
||||
def inspection(row)
|
||||
{ inspection_type_id: row.type.id, name: row.type.name, status: row.status, next_due_date: row.next_due_date&.iso8601,
|
||||
next_due_hours: dec(row.next_due_hours), last_done: row.latest&.date&.iso8601 }
|
||||
end
|
||||
|
||||
def ad(row)
|
||||
{ airworthiness_directive_id: row.ad.id, name: row.ad.name, description: row.ad.short_description.presence,
|
||||
status: row.status, next_due_date: row.next_due_date&.iso8601, next_due_hours: dec(row.next_due_hours),
|
||||
last_complied: row.latest&.date_complied&.iso8601 }
|
||||
end
|
||||
|
||||
def dec(value) = value&.to_d&.round(1)&.to_f
|
||||
def time(value) = value&.utc&.iso8601
|
||||
end
|
||||
@@ -30,9 +30,6 @@ class AirTrailClient
|
||||
@allow_private = allow_private || self.class.allowed_hosts.include?(@base.host.to_s.downcase)
|
||||
end
|
||||
|
||||
# Host name → IP addresses (replaceable in tests, which have no DNS).
|
||||
class_attribute :resolver, default: ->(host) { Addrinfo.getaddrinfo(host, nil, nil, :STREAM).map(&:ip_address) }
|
||||
|
||||
def self.allowed_hosts = ENV.fetch("AIRTRAIL_ALLOWED_HOSTS", "").split(",").map { _1.strip.downcase }.compact_blank
|
||||
|
||||
def me = request(:get, "/api/v1/me").fetch("data")
|
||||
@@ -85,23 +82,12 @@ class AirTrailClient
|
||||
raise NetworkError, I18n.t("services.air_trail.can_t_reach_airtrail_at", host: @base.host, message: e.message)
|
||||
end
|
||||
|
||||
# The address to connect to: the host's first, once all of its addresses are
|
||||
# ones this connection may reach.
|
||||
# The address to connect to (see OutboundAddress).
|
||||
def address(host)
|
||||
ips = resolver.call(host).map { IPAddr.new(_1.sub(/%.*/, "")) }.uniq
|
||||
raise SocketError, "no address" if ips.empty?
|
||||
ips.each do |ip|
|
||||
ip = ip.native # ::ffff:10.0.0.1 → 10.0.0.1
|
||||
reason = if ip.loopback? || ip.link_local? || UNREACHABLE.any? { _1.include?(ip) } then :never
|
||||
elsif (ip.private? || CGNAT.include?(ip)) && !@allow_private then :private
|
||||
OutboundAddress.resolve!(host, allow_private: @allow_private)
|
||||
rescue OutboundAddress::Blocked => e
|
||||
raise BlockedAddress, I18n.t("services.air_trail.blocked_#{e.reason}", host: host)
|
||||
end
|
||||
raise BlockedAddress, I18n.t("services.air_trail.blocked_#{reason}", host: host) if reason
|
||||
end
|
||||
ips.first.to_s
|
||||
end
|
||||
|
||||
UNREACHABLE = [ IPAddr.new("0.0.0.0/8"), IPAddr.new("::/128"), IPAddr.new("224.0.0.0/4"), IPAddr.new("ff00::/8") ].freeze
|
||||
CGNAT = IPAddr.new("100.64.0.0/10") # shared address space, e.g. Tailscale
|
||||
|
||||
def handle(response)
|
||||
status = response.code.to_i
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
# Checks where the server is about to send a request (AirTrail, webhooks):
|
||||
# resolves the host and returns the address to connect to, so the name can't
|
||||
# be pointed elsewhere in between. Never the server itself, link-local
|
||||
# addresses (cloud metadata) or multicast; the private network only when
|
||||
# allowed (admins, or hosts the admin listed).
|
||||
module OutboundAddress
|
||||
class Blocked < StandardError
|
||||
attr_reader :reason # :never | :private
|
||||
|
||||
def initialize(reason, host)
|
||||
@reason = reason
|
||||
super("#{host}: #{reason}")
|
||||
end
|
||||
end
|
||||
|
||||
UNREACHABLE = [ IPAddr.new("0.0.0.0/8"), IPAddr.new("::/128"), IPAddr.new("224.0.0.0/4"), IPAddr.new("ff00::/8") ].freeze
|
||||
CGNAT = IPAddr.new("100.64.0.0/10") # shared address space, e.g. Tailscale
|
||||
|
||||
# Host name → IP addresses (replaceable in tests, which have no DNS).
|
||||
mattr_accessor :resolver, default: ->(host) { Addrinfo.getaddrinfo(host, nil, nil, :STREAM).map(&:ip_address) }
|
||||
|
||||
module_function
|
||||
|
||||
def resolve!(host, allow_private:)
|
||||
ips = resolver.call(host).map { IPAddr.new(_1.sub(/%.*/, "")) }.uniq
|
||||
raise SocketError, "no address for #{host}" if ips.empty?
|
||||
ips.each do |ip|
|
||||
ip = ip.native # ::ffff:10.0.0.1 → 10.0.0.1
|
||||
raise Blocked.new(:never, host) if ip.loopback? || ip.link_local? || UNREACHABLE.any? { _1.include?(ip) }
|
||||
raise Blocked.new(:private, host) if (ip.private? || CGNAT.include?(ip)) && !allow_private
|
||||
end
|
||||
ips.first.to_s
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,16 @@
|
||||
# What happens when a squawk is reported, from the form or the API: the
|
||||
# aircraft's activity log, and a push notification to its other people when
|
||||
# it grounds the aircraft.
|
||||
module SquawkReported
|
||||
module_function
|
||||
|
||||
def call(squawk, by:)
|
||||
aircraft = squawk.aircraft
|
||||
aircraft.log_event!("squawk", I18n.t("flash.squawks.squawk_reported_2", priority_label: squawk.priority_label),
|
||||
user: by, notes: squawk.issue_reported.truncate(200))
|
||||
return unless squawk.grounding?
|
||||
PushNotifier.notify(aircraft.users.merge(User.active).where.not(id: by&.id), :grounding_squawk,
|
||||
path: Rails.application.routes.url_helpers.aircraft_squawks_path(aircraft),
|
||||
tag: "squawk-#{squawk.id}", tail: aircraft.tail_number, issue: squawk.issue_reported.truncate(120))
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,18 @@
|
||||
# Tells integrations about changes (docs/api.md, "Webhooks"): each enabled
|
||||
# endpoint subscribed to the event, whose token is active and reaches the
|
||||
# aircraft, gets a delivery, sent by WebhookDeliveryJob after the change is
|
||||
# saved.
|
||||
module Webhooks
|
||||
module_function
|
||||
|
||||
def publish(event, aircraft:, data:)
|
||||
endpoints = WebhookEndpoint.enabled.joins(:api_token).merge(ApiToken.active).includes(:api_token)
|
||||
.select { _1.subscribed?(event) && Array(_1.api_token.aircraft_ids).include?(aircraft.id) }
|
||||
return if endpoints.empty?
|
||||
body = { event: event, id: SecureRandom.uuid, created_at: Time.current.utc.iso8601, aircraft_id: aircraft.id, data: data }.to_json
|
||||
endpoints.each do |endpoint|
|
||||
delivery = endpoint.deliveries.create!(event: event, payload: body)
|
||||
WebhookDeliveryJob.perform_later(delivery.id)
|
||||
end
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,32 @@
|
||||
<%= form_with model: integration, url: (integration.persisted? ? admin_integration_path(integration) : admin_integrations_path), scope: :api_token,
|
||||
class: "card card-body max-w-2xl space-y-5", data: { turbo: false } do |f| %>
|
||||
<%= f.errors_summary %>
|
||||
<% if endpoint&.errors&.any? %><div class="rounded-md bg-red-50 p-3 text-sm text-red-700"><%= endpoint.errors.full_messages.to_sentence %></div><% end %>
|
||||
<%= f.field :name, hint: t(".name_hint") %>
|
||||
<fieldset>
|
||||
<legend class="label"><%= t(".scopes") %></legend>
|
||||
<% ApiToken::SCOPES.each do |key, label| %>
|
||||
<label class="flex items-start gap-2 text-sm"><%= check_box_tag "api_token[scopes][]", key, integration.scopes.include?(key), id: "scope_#{key.parameterize}", class: "mt-1" %> <span><%= label %></span></label>
|
||||
<% end %>
|
||||
</fieldset>
|
||||
<fieldset>
|
||||
<legend class="label"><%= t(".aircraft") %></legend>
|
||||
<p class="hint mb-1"><%= t(".aircraft_hint") %></p>
|
||||
<% Aircraft.ordered.each do |a| %>
|
||||
<label class="mr-4 inline-flex items-center gap-2 text-sm"><%= check_box_tag "api_token[aircraft_ids][]", a.id, Array(integration.aircraft_ids).include?(a.id), id: "aircraft_#{a.id}" %> <%= a.tail_number %></label>
|
||||
<% end %>
|
||||
</fieldset>
|
||||
<fieldset class="space-y-2 border-t border-slate-200 pt-4">
|
||||
<legend class="label"><%= t(".webhook") %></legend>
|
||||
<p class="hint"><%= t(".webhook_hint") %></p>
|
||||
<%= url_field_tag "webhook[url]", endpoint&.url, class: "input", placeholder: "https://redmine.example.com/sam/webhook", "aria-label": t(".webhook_url") %>
|
||||
<% WebhookEndpoint::EVENTS.each do |key, label| %>
|
||||
<label class="flex items-start gap-2 text-sm"><%= check_box_tag "webhook[events][]", key, Array(endpoint&.events).include?(key), id: "event_#{key.parameterize}", class: "mt-1" %> <span><%= label %> <code class="text-xs text-slate-500"><%= key %></code></span></label>
|
||||
<% end %>
|
||||
<% if endpoint&.persisted? %>
|
||||
<%= hidden_field_tag "webhook[enabled]", "0", id: nil %>
|
||||
<label class="flex items-center gap-2 text-sm"><%= check_box_tag "webhook[enabled]", "1", endpoint.enabled %> <%= t(".webhook_enabled") %></label>
|
||||
<% end %>
|
||||
</fieldset>
|
||||
<%= f.submit integration.persisted? ? t(".save") : t(".create"), class: "btn-primary" %>
|
||||
<% end %>
|
||||
@@ -0,0 +1,15 @@
|
||||
<% content_for :title, @integration.name %>
|
||||
<section class="card card-body max-w-xl space-y-3">
|
||||
<h1 class="card-title"><%= @integration.name %></h1>
|
||||
<p class="text-sm text-slate-600"><%= t(".copy_now") %></p>
|
||||
<% if @integration.token %>
|
||||
<label class="label" for="integration_token"><%= t(".token") %></label>
|
||||
<input id="integration_token" class="input font-mono text-sm" value="<%= @integration.token %>" readonly>
|
||||
<% end %>
|
||||
<% if @secret %>
|
||||
<label class="label" for="webhook_secret"><%= t(".webhook_secret") %></label>
|
||||
<input id="webhook_secret" class="input font-mono text-sm" value="<%= @secret %>" readonly>
|
||||
<p class="hint"><%= t(".secret_hint") %></p>
|
||||
<% end %>
|
||||
<p><%= link_to t(".done"), admin_integration_path(@integration), class: "btn-primary" %></p>
|
||||
</section>
|
||||
@@ -0,0 +1,3 @@
|
||||
<% content_for :title, @integration.name %>
|
||||
<h1 class="mb-4 text-2xl font-bold"><%= @integration.name %></h1>
|
||||
<%= render "form", integration: @integration, endpoint: @endpoint %>
|
||||
@@ -0,0 +1,17 @@
|
||||
<% content_for :title, t(".integrations") %>
|
||||
<div class="mb-4 flex items-center justify-between"><h1 class="text-2xl font-bold"><%= t(".integrations") %></h1><%= link_to t(".new_integration"), new_admin_integration_path, class: "btn-primary" %></div>
|
||||
<p class="mb-4 max-w-3xl text-sm text-slate-600"><%= t(".what_html", docs: link_to(t(".api_docs"), help_page_path("api"), class: "link")) %></p>
|
||||
<% if @integrations.any? %>
|
||||
<section class="card"><table class="table">
|
||||
<thead><tr><th><%= t(".name") %></th><th><%= t(".aircraft") %></th><th><%= t(".webhook") %></th><th><%= t(".last_used") %></th></tr></thead>
|
||||
<tbody><% @integrations.each do |i| %><tr>
|
||||
<td><%= link_to i.name, admin_integration_path(i), class: "link font-medium" %> <% if i.revoked? %><span class="badge-red"><%= t(".revoked") %></span><% end %>
|
||||
<div class="text-xs text-slate-500"><code><%= i.token_hint %>…</code></div></td>
|
||||
<td class="text-xs"><%= Aircraft.where(id: Array(i.aircraft_ids)).order(:tail_number).pluck(:tail_number).join(", ").presence || "—" %></td>
|
||||
<td class="text-xs"><%= (e = i.webhook_endpoints.first) ? e.url : "—" %></td>
|
||||
<td class="text-xs text-slate-500"><%= i.last_used_at ? t(".ago", ago: time_ago_in_words(i.last_used_at)) : t(".never") %></td>
|
||||
</tr><% end %></tbody>
|
||||
</table></section>
|
||||
<% else %>
|
||||
<%= empty_state t(".none_yet") %>
|
||||
<% end %>
|
||||
@@ -0,0 +1,3 @@
|
||||
<% content_for :title, t(".new_integration") %>
|
||||
<h1 class="mb-4 text-2xl font-bold"><%= t(".new_integration") %></h1>
|
||||
<%= render "form", integration: @integration, endpoint: @endpoint %>
|
||||
@@ -0,0 +1,49 @@
|
||||
<% content_for :title, @integration.name %>
|
||||
<div class="mb-4 flex flex-wrap items-center justify-between gap-3">
|
||||
<h1 class="text-2xl font-bold"><%= @integration.name %> <% if @integration.revoked? %><span class="badge-red align-middle text-sm"><%= t(".revoked") %></span><% end %></h1>
|
||||
<% unless @integration.revoked? %>
|
||||
<div class="flex gap-2">
|
||||
<%= link_to t(".edit"), edit_admin_integration_path(@integration), class: "btn-secondary" %>
|
||||
<%= button_to t(".revoke"), admin_integration_path(@integration), method: :delete, class: "btn-danger",
|
||||
form: { data: { turbo_confirm: t(".revoke_confirm", name: @integration.name) } } %>
|
||||
</div>
|
||||
<% end %>
|
||||
</div>
|
||||
<div class="grid max-w-5xl items-start gap-5 lg:grid-cols-2">
|
||||
<section class="card card-body">
|
||||
<h2 class="card-title"><%= t(".token") %></h2>
|
||||
<dl class="mt-2 grid gap-y-2 text-sm">
|
||||
<div class="detail-row"><dt><%= t(".hint") %></dt><dd><code><%= @integration.token_hint %>…</code></dd></div>
|
||||
<div class="detail-row"><dt><%= t(".scopes") %></dt><dd><%= @integration.scopes.map { ApiToken::SCOPES[_1] }.to_sentence %></dd></div>
|
||||
<div class="detail-row"><dt><%= t(".aircraft") %></dt><dd><%= Aircraft.where(id: Array(@integration.aircraft_ids)).order(:tail_number).pluck(:tail_number).join(", ").presence || "—" %></dd></div>
|
||||
<div class="detail-row"><dt><%= t(".created") %></dt><dd><%= fmt_time(@integration.created_at) %> · <%= @integration.user.display_name %></dd></div>
|
||||
<div class="detail-row"><dt><%= t(".last_used") %></dt><dd><%= @integration.last_used_at ? "#{fmt_time(@integration.last_used_at)} · #{@integration.last_used_ip}" : t(".never") %></dd></div>
|
||||
</dl>
|
||||
</section>
|
||||
<section class="card card-body">
|
||||
<h2 class="card-title"><%= t(".webhook") %></h2>
|
||||
<% if @endpoint %>
|
||||
<dl class="mt-2 grid gap-y-2 text-sm">
|
||||
<div class="detail-row"><dt><%= t(".url") %></dt><dd class="break-all"><%= @endpoint.url %> <% unless @endpoint.enabled %><span class="badge-gray"><%= t(".paused") %></span><% end %></dd></div>
|
||||
<div class="detail-row"><dt><%= t(".events") %></dt><dd><%= @endpoint.events.map { WebhookEndpoint::EVENTS[_1] }.to_sentence %></dd></div>
|
||||
</dl>
|
||||
<% unless @integration.revoked? %>
|
||||
<div class="mt-3"><%= button_to t(".new_secret"), new_secret_admin_integration_path(@integration), class: "btn-secondary btn-sm",
|
||||
form: { data: { turbo: false, turbo_confirm: t(".new_secret_confirm") } } %></div>
|
||||
<% end %>
|
||||
<% else %>
|
||||
<p class="mt-1 text-sm text-slate-600"><%= t(".no_webhook") %></p>
|
||||
<% end %>
|
||||
</section>
|
||||
</div>
|
||||
<% if @deliveries.any? %>
|
||||
<section class="card mt-5 max-w-5xl">
|
||||
<div class="card-header"><h2 class="card-title"><%= t(".recent_deliveries") %></h2></div>
|
||||
<table class="table"><thead><tr><th><%= t(".when") %></th><th><%= t(".event") %></th><th><%= t(".result") %></th></tr></thead>
|
||||
<tbody><% @deliveries.each do |d| %><tr>
|
||||
<td class="text-xs"><%= fmt_time(d.created_at) %></td><td><code class="text-xs"><%= d.event %></code></td>
|
||||
<td class="text-xs"><span class="<%= { "delivered" => "badge-green", "failed" => "badge-red" }.fetch(d.status, "badge-gray") %>"><%= t(".status.#{d.status}") %></span>
|
||||
<%= d.response_status %> <%= d.last_error %> <% if d.attempts > 1 %>· <%= t(".attempts", count: d.attempts) %><% end %></td>
|
||||
</tr><% end %></tbody></table>
|
||||
</section>
|
||||
<% end %>
|
||||
@@ -0,0 +1,8 @@
|
||||
<% content_for :title, t(".title") %>
|
||||
<section class="card card-body max-w-xl space-y-3">
|
||||
<h1 class="card-title"><%= t(".title") %></h1>
|
||||
<p class="text-sm text-slate-600"><%= t(".copy_now", name: @token.name) %></p>
|
||||
<input class="input font-mono text-sm" value="<%= @token.token %>" readonly aria-label="<%= t(".token") %>">
|
||||
<p class="hint"><%= t(".how_to_use_html") %></p>
|
||||
<p><%= link_to t(".done"), edit_profile_path(anchor: "api"), class: "btn-primary" %></p>
|
||||
</section>
|
||||
@@ -46,7 +46,7 @@
|
||||
<%= link_to t(".help"), help_path, class: "block px-4 py-2.5 hover:bg-slate-100" %>
|
||||
<% if current_user.admin? %>
|
||||
<p class="border-t border-slate-100 px-4 pt-2 pb-1 text-xs font-semibold text-slate-500"><%= t(".admin") %></p>
|
||||
<% [ [ t(".users"), admin_users_path ], [ t(".component_types"), admin_component_types_path ], [ t(".airports"), admin_airports_path ], [ t(".logbook_templates"), admin_logbook_templates_path ], [ t(".settings"), edit_admin_settings_path ], [ t(".off_site_backup"), admin_offsite_backup_path ], [ t(".recordkeeping_procedures"), admin_procedures_path ], [ t(".records_audits"), admin_audits_path ], [ t(".about"), admin_about_path ] ].each do |label, path| %>
|
||||
<% [ [ t(".users"), admin_users_path ], [ t(".integrations"), admin_integrations_path ], [ t(".component_types"), admin_component_types_path ], [ t(".airports"), admin_airports_path ], [ t(".logbook_templates"), admin_logbook_templates_path ], [ t(".settings"), edit_admin_settings_path ], [ t(".off_site_backup"), admin_offsite_backup_path ], [ t(".recordkeeping_procedures"), admin_procedures_path ], [ t(".records_audits"), admin_audits_path ], [ t(".about"), admin_about_path ] ].each do |label, path| %>
|
||||
<%= link_to label, path, class: "block px-4 py-2.5 hover:bg-slate-100" %>
|
||||
<% end %>
|
||||
<% end %>
|
||||
@@ -67,7 +67,7 @@
|
||||
<%= t(".admin") %> <span aria-hidden="true" class="text-xs">▾</span>
|
||||
</summary>
|
||||
<div class="absolute right-0 z-30 mt-2 w-48 rounded-md bg-surface py-1 text-slate-700 shadow-lg ring-1 ring-slate-200">
|
||||
<% [ [ t(".users"), admin_users_path ], [ t(".component_types"), admin_component_types_path ], [ t(".airports"), admin_airports_path ], [ t(".logbook_templates"), admin_logbook_templates_path ], [ t(".settings"), edit_admin_settings_path ], [ t(".off_site_backup"), admin_offsite_backup_path ], [ t(".recordkeeping_procedures"), admin_procedures_path ], [ t(".records_audits"), admin_audits_path ], [ t(".about"), admin_about_path ] ].each do |label, path| %>
|
||||
<% [ [ t(".users"), admin_users_path ], [ t(".integrations"), admin_integrations_path ], [ t(".component_types"), admin_component_types_path ], [ t(".airports"), admin_airports_path ], [ t(".logbook_templates"), admin_logbook_templates_path ], [ t(".settings"), edit_admin_settings_path ], [ t(".off_site_backup"), admin_offsite_backup_path ], [ t(".recordkeeping_procedures"), admin_procedures_path ], [ t(".records_audits"), admin_audits_path ], [ t(".about"), admin_about_path ] ].each do |label, path| %>
|
||||
<%= link_to label, path, class: [ "block px-4 py-2 text-sm hover:bg-slate-100", ("font-semibold text-sky-700" if current_page?(path)) ] %>
|
||||
<% end %>
|
||||
</div>
|
||||
|
||||
@@ -136,6 +136,34 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="card card-body" id="api">
|
||||
<h2 class="card-title"><%= t(".api_tokens") %></h2>
|
||||
<p class="mt-1 text-sm text-slate-600"><%= t(".api_tokens_what_html", docs: link_to(t(".api_docs"), help_page_path("api"), class: "link")) %></p>
|
||||
<% tokens = @user.api_tokens.personal.active.order(:created_at) %>
|
||||
<% if tokens.any? %>
|
||||
<ul class="mt-3 divide-y divide-slate-100 rounded-md ring-1 ring-slate-200">
|
||||
<% tokens.each do |token| %>
|
||||
<li class="flex flex-wrap items-center justify-between gap-2 px-3 py-2 text-sm">
|
||||
<span><span class="font-medium"><%= token.name %></span> <code class="text-xs text-slate-500"><%= token.token_hint %>…</code>
|
||||
<span class="block text-xs text-slate-500"><%= token.scopes.map { ApiToken::SCOPES[_1] }.to_sentence %> ·
|
||||
<%= token.last_used_at ? t(".api_token_used", ago: time_ago_in_words(token.last_used_at)) : t(".api_token_unused") %></span></span>
|
||||
<%= button_to t(".revoke"), api_token_path(token), method: :delete, class: "btn-secondary btn-sm",
|
||||
form: { data: { turbo_confirm: t(".revoke_token", name: token.name) } } %>
|
||||
</li>
|
||||
<% end %>
|
||||
</ul>
|
||||
<% end %>
|
||||
<%= form_with model: ApiToken.new, url: api_tokens_path, class: "mt-3 space-y-2", data: { turbo: false } do |f| %>
|
||||
<%= f.text_field :name, class: "input", placeholder: t(".api_token_name"), required: true, maxlength: 80, "aria-label": t(".api_token_name") %>
|
||||
<fieldset class="space-y-1 text-sm">
|
||||
<% ApiToken::SCOPES.each do |key, label| %>
|
||||
<label class="flex items-start gap-2"><%= check_box_tag "api_token[scopes][]", key, key == "read", id: "api_token_scope_#{key.parameterize}", class: "mt-1" %> <span><%= label %></span></label>
|
||||
<% end %>
|
||||
</fieldset>
|
||||
<%= f.submit t(".create_api_token"), class: "btn-secondary" %>
|
||||
<% end %>
|
||||
</section>
|
||||
|
||||
<section class="card card-body">
|
||||
<h2 class="card-title"><%= t(".integrations") %></h2>
|
||||
<p class="mt-1 text-sm text-slate-600">
|
||||
|
||||
@@ -4,7 +4,26 @@
|
||||
# a controller name are its views (t(".key") in the view).
|
||||
|
||||
en:
|
||||
api_tokens:
|
||||
created:
|
||||
title: Your new API token
|
||||
copy_now: "Copy the token for %{name} now: it isn't shown again (only its first characters are kept, to tell tokens apart)."
|
||||
token: API token
|
||||
how_to_use_html: 'Send it with each request: <code>Authorization: Bearer <token></code>. See the API reference in Help.'
|
||||
done: Done
|
||||
labels:
|
||||
api_token:
|
||||
scopes:
|
||||
read: Read aircraft, parts, due items, squawks and logbook entries
|
||||
'squawks:write': Report and update squawks
|
||||
webhook_endpoint:
|
||||
events:
|
||||
squawk:
|
||||
created: A squawk is reported
|
||||
updated: A squawk is changed
|
||||
resolved: A squawk is resolved
|
||||
entry:
|
||||
signed: A logbook entry is signed
|
||||
aircraft:
|
||||
statuses:
|
||||
AVAILABLE: Available
|
||||
@@ -286,6 +305,10 @@ en:
|
||||
signed_locked: This entry is signed, so it can't be changed. Make a correction entry instead
|
||||
squawk:
|
||||
confirm: 'Confirm: %{check}'
|
||||
api_token:
|
||||
attributes:
|
||||
kind:
|
||||
admins_only: "integration tokens can only be made by an administrator"
|
||||
ad_compliance:
|
||||
needs_owner: Must belong to an aircraft or component
|
||||
attributes:
|
||||
@@ -705,6 +728,11 @@ en:
|
||||
envelope_weights: Envelope weights must be more than 0
|
||||
fuel_weight: Fuel weight per gallon must be between 4 and 9 lb
|
||||
flash:
|
||||
admin_integrations:
|
||||
saved: Integration saved.
|
||||
revoked: "%{name} revoked: its token no longer works and its webhook is stopped."
|
||||
api_tokens:
|
||||
revoked: Token revoked. Programs using it can no longer connect.
|
||||
push_subscriptions:
|
||||
not_saved: "This browser's push service (%{host}) isn't one the app sends to."
|
||||
unknown_device: Unknown browser
|
||||
@@ -1180,6 +1208,69 @@ en:
|
||||
matches: Matches
|
||||
update: Update
|
||||
admin:
|
||||
integrations:
|
||||
show:
|
||||
revoked: Revoked
|
||||
edit: Edit
|
||||
revoke: Revoke
|
||||
revoke_confirm: "Revoke %{name}? Its token stops working at once and its webhook stops. This can't be undone; make a new integration to reconnect."
|
||||
token: Token
|
||||
hint: Starts with
|
||||
scopes: May
|
||||
aircraft: Aircraft
|
||||
created: Created
|
||||
last_used: Last used
|
||||
never: never
|
||||
webhook: Webhook
|
||||
url: Address
|
||||
paused: Paused
|
||||
events: Events
|
||||
new_secret: New secret
|
||||
new_secret_confirm: "Make a new webhook secret? The other system needs the new one; webhooks signed with the old one will fail its check."
|
||||
no_webhook: "None: the system only calls the API."
|
||||
recent_deliveries: Recent webhooks
|
||||
when: When
|
||||
event: Event
|
||||
result: Result
|
||||
attempts:
|
||||
one: "%{count} attempt"
|
||||
other: "%{count} attempts"
|
||||
status:
|
||||
pending: Pending
|
||||
delivered: Delivered
|
||||
failed: Failed
|
||||
created:
|
||||
copy_now: "Copy these now: they aren't shown again."
|
||||
token: API token
|
||||
webhook_secret: Webhook secret
|
||||
secret_hint: The other system checks each webhook with it (see the API reference).
|
||||
done: Done
|
||||
new:
|
||||
new_integration: New integration
|
||||
form:
|
||||
name_hint: The system it's for, e.g. Redmine.
|
||||
scopes: What it may do
|
||||
aircraft: Aircraft it may reach
|
||||
aircraft_hint: When it acts for a person, only those of these aircraft that person can see.
|
||||
webhook: Webhook (optional)
|
||||
webhook_hint: "Where to post changes. Each post is signed with a secret shown once after saving (header SAM-Signature)."
|
||||
webhook_url: Webhook address
|
||||
webhook_enabled: Send webhooks
|
||||
save: Save
|
||||
create: Create integration
|
||||
index:
|
||||
integrations: Integrations
|
||||
new_integration: New integration
|
||||
what_html: "Let another system, such as Redmine, work with the aircraft through the REST API (%{docs}). Each integration has its own token, limited to the aircraft and actions you choose; its changes name the person they're for, so the record history shows who. It can be told about changes by webhook."
|
||||
api_docs: API reference
|
||||
name: Name
|
||||
aircraft: Aircraft
|
||||
webhook: Webhook
|
||||
last_used: Last used
|
||||
revoked: Revoked
|
||||
ago: "%{ago} ago"
|
||||
never: never
|
||||
none_yet: No integrations yet.
|
||||
about:
|
||||
show:
|
||||
about: About
|
||||
@@ -2471,6 +2562,7 @@ en:
|
||||
sign_out: Sign out
|
||||
layouts:
|
||||
application:
|
||||
integrations: Integrations
|
||||
skip_to_content_html: <a href="#main" class="skip-link">Skip to content</a>
|
||||
simple_aircraft_manager: Simple Aircraft Manager
|
||||
sam: SAM
|
||||
@@ -2946,6 +3038,15 @@ en:
|
||||
subject: Reset your password
|
||||
profiles:
|
||||
edit:
|
||||
revoke: Revoke
|
||||
api_tokens: API tokens
|
||||
api_tokens_what_html: "Keys for scripts and other programs to read your aircraft and report squawks through the REST API, acting as you (%{docs}). Treat a token like a password: anyone who has it can do what it allows."
|
||||
api_docs: API reference
|
||||
api_token_used: used %{ago} ago
|
||||
api_token_unused: never used
|
||||
revoke_token: "Revoke %{name}? Programs using it stop working."
|
||||
api_token_name: Name (what it's for)
|
||||
create_api_token: Create token
|
||||
your_profile: Your Profile
|
||||
account: Account
|
||||
email: Email
|
||||
|
||||
@@ -18,6 +18,9 @@ production:
|
||||
purge_abandoned_uploads:
|
||||
command: "ActiveStorage::Blob.unattached.where(created_at: ..2.days.ago).find_each(&:purge_later)"
|
||||
schedule: every day at 4am <%= zone %>
|
||||
purge_api_records:
|
||||
command: "ApiIdempotencyKey.purge_old; WebhookDelivery.purge_old"
|
||||
schedule: every day at 4:15am <%= zone %>
|
||||
dedupe_storage:
|
||||
command: "ActiveStorage::Blob.service.try(:sweep)"
|
||||
schedule: every day at 4:30am <%= zone %>
|
||||
|
||||
@@ -27,6 +27,7 @@ Rails.application.routes.draw do
|
||||
# Home-screen shortcuts: the form for your aircraft, or a choice of aircraft.
|
||||
get "go/log-flight", to: "shortcuts#log_flight", as: :log_flight_shortcut
|
||||
get "go/report-squawk", to: "shortcuts#report_squawk", as: :report_squawk_shortcut
|
||||
resources :api_tokens, path: "profile/api_tokens", only: %i[create destroy]
|
||||
resources :certificates, path: "profile/certificates", controller: "user_certificates", only: %i[create update destroy]
|
||||
resource :air_trail_connection, path: "profile/airtrail", only: %i[show create update destroy] do
|
||||
post :test
|
||||
@@ -171,12 +172,34 @@ Rails.application.routes.draw do
|
||||
post "about/test_reminder", to: "about#test_reminder", as: :test_reminder
|
||||
post "about/check_records", to: "about#check_records", as: :check_records
|
||||
resources :users, except: :show
|
||||
resources :integrations do
|
||||
post :new_secret, on: :member
|
||||
end
|
||||
resources :component_types, except: :show
|
||||
resources :airports, except: :show do
|
||||
collection { post :refresh }
|
||||
end
|
||||
end
|
||||
|
||||
# REST API (docs/api.md): bearer tokens, JSON.
|
||||
namespace :api, defaults: { format: :json } do
|
||||
namespace :v1 do
|
||||
get "me", to: "me#show"
|
||||
resources :aircraft, only: %i[index show] do
|
||||
member do
|
||||
get :components
|
||||
get :due
|
||||
get :inspections
|
||||
get :ads
|
||||
get :logbook_entries
|
||||
end
|
||||
resources :squawks, only: %i[index create]
|
||||
end
|
||||
get "squawks", to: "squawks#lookup"
|
||||
resources :squawks, only: %i[show update]
|
||||
end
|
||||
end
|
||||
|
||||
get "up" => "rails/health#show", as: :rails_health_check
|
||||
get "manifest" => "rails/pwa#manifest", as: :pwa_manifest
|
||||
get "offline" => "offline#show", as: :offline
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# The REST API (docs/api.md): tokens, webhooks, idempotent writes, and links
|
||||
# from SAM records to the other system's ids ("redmine:issue:4512").
|
||||
class CreateApi < ActiveRecord::Migration[8.1]
|
||||
def change
|
||||
create_table :api_tokens do |t|
|
||||
t.string :name, null: false
|
||||
t.string :kind, null: false, default: "personal" # personal | integration
|
||||
t.references :user, null: false, foreign_key: true # the owner (personal) or the admin who made it (integration)
|
||||
t.string :token_digest, null: false
|
||||
t.string :token_hint, null: false # the first characters, to tell tokens apart
|
||||
t.json :scopes, null: false, default: []
|
||||
t.json :aircraft_ids # integration: the aircraft it may reach
|
||||
t.datetime :last_used_at
|
||||
t.string :last_used_ip
|
||||
t.datetime :revoked_at
|
||||
t.timestamps
|
||||
t.index :token_digest, unique: true
|
||||
end
|
||||
|
||||
create_table :webhook_endpoints do |t|
|
||||
t.references :api_token, null: false, foreign_key: true
|
||||
t.string :url, null: false
|
||||
t.text :secret, null: false
|
||||
t.json :events, null: false, default: []
|
||||
t.boolean :enabled, null: false, default: true
|
||||
t.timestamps
|
||||
end
|
||||
|
||||
create_table :webhook_deliveries do |t|
|
||||
t.references :webhook_endpoint, null: false, foreign_key: true
|
||||
t.string :event, null: false
|
||||
t.text :payload, null: false
|
||||
t.string :status, null: false, default: "pending" # pending | delivered | failed
|
||||
t.integer :attempts, null: false, default: 0
|
||||
t.integer :response_status
|
||||
t.string :last_error
|
||||
t.datetime :delivered_at
|
||||
t.timestamps
|
||||
t.index [ :webhook_endpoint_id, :created_at ]
|
||||
end
|
||||
|
||||
create_table :api_idempotency_keys do |t|
|
||||
t.references :api_token, null: false, foreign_key: true
|
||||
t.string :key, null: false
|
||||
t.string :request_digest, null: false
|
||||
t.integer :response_status, null: false
|
||||
t.text :response_body, null: false
|
||||
t.datetime :created_at, null: false
|
||||
t.index [ :api_token_id, :key ], unique: true
|
||||
end
|
||||
|
||||
add_column :squawks, :external_ref, :string
|
||||
add_index :squawks, :external_ref
|
||||
add_column :record_versions, :api_token_id, :integer
|
||||
end
|
||||
end
|
||||
Generated
+63
-2
@@ -10,7 +10,7 @@
|
||||
#
|
||||
# It's strongly recommended that you check this file into your version control system.
|
||||
|
||||
ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do
|
||||
ActiveRecord::Schema[8.1].define(version: 2026_11_15_010000) do
|
||||
create_table "active_storage_attachments", force: :cascade do |t|
|
||||
t.string "name", null: false
|
||||
t.string "record_type", null: false
|
||||
@@ -289,6 +289,34 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do
|
||||
t.index ["component_id", "airworthiness_directive_id"], name: "idx_component_ads", unique: true
|
||||
end
|
||||
|
||||
create_table "api_idempotency_keys", force: :cascade do |t|
|
||||
t.integer "api_token_id", null: false
|
||||
t.string "key", null: false
|
||||
t.string "request_digest", null: false
|
||||
t.integer "response_status", null: false
|
||||
t.text "response_body", null: false
|
||||
t.datetime "created_at", null: false
|
||||
t.index ["api_token_id", "key"], name: "index_api_idempotency_keys_on_api_token_id_and_key", unique: true
|
||||
t.index ["api_token_id"], name: "index_api_idempotency_keys_on_api_token_id"
|
||||
end
|
||||
|
||||
create_table "api_tokens", force: :cascade do |t|
|
||||
t.string "name", null: false
|
||||
t.string "kind", default: "personal", null: false
|
||||
t.integer "user_id", null: false
|
||||
t.string "token_digest", null: false
|
||||
t.string "token_hint", null: false
|
||||
t.json "scopes", default: [], null: false
|
||||
t.json "aircraft_ids"
|
||||
t.datetime "last_used_at"
|
||||
t.string "last_used_ip"
|
||||
t.datetime "revoked_at"
|
||||
t.datetime "created_at", null: false
|
||||
t.datetime "updated_at", null: false
|
||||
t.index ["token_digest"], name: "index_api_tokens_on_token_digest", unique: true
|
||||
t.index ["user_id"], name: "index_api_tokens_on_user_id"
|
||||
end
|
||||
|
||||
create_table "app_revisions", force: :cascade do |t|
|
||||
t.string "revision", null: false
|
||||
t.datetime "built_at"
|
||||
@@ -347,13 +375,13 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do
|
||||
t.boolean "tbo_critical", default: true, null: false
|
||||
t.boolean "on_condition", default: false, null: false
|
||||
t.boolean "replacement_critical", default: false, null: false
|
||||
t.boolean "replacement_from_install", default: false, null: false
|
||||
t.datetime "created_at", null: false
|
||||
t.datetime "updated_at", null: false
|
||||
t.date "expires_on"
|
||||
t.string "overhaul_kind"
|
||||
t.integer "replacement_months"
|
||||
t.integer "tbo_months"
|
||||
t.boolean "replacement_from_install", default: false, null: false
|
||||
t.index ["aircraft_id"], name: "index_components_on_aircraft_id"
|
||||
t.index ["component_type_id"], name: "index_components_on_component_type_id"
|
||||
t.index ["parent_component_id"], name: "index_components_on_parent_component_id"
|
||||
@@ -719,6 +747,7 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do
|
||||
t.string "prev_hash"
|
||||
t.string "chain_hash", null: false
|
||||
t.datetime "created_at", null: false
|
||||
t.integer "api_token_id"
|
||||
t.index ["aircraft_id"], name: "index_record_versions_on_aircraft_id"
|
||||
t.index ["item_type", "item_id"], name: "index_record_versions_on_item_type_and_item_id"
|
||||
end
|
||||
@@ -802,9 +831,11 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do
|
||||
t.text "deferral_notes"
|
||||
t.integer "logbook_entry_id"
|
||||
t.string "client_key"
|
||||
t.string "external_ref"
|
||||
t.index ["aircraft_id", "client_key"], name: "index_squawks_on_aircraft_id_and_client_key", unique: true
|
||||
t.index ["aircraft_id"], name: "index_squawks_on_aircraft_id"
|
||||
t.index ["component_id"], name: "index_squawks_on_component_id"
|
||||
t.index ["external_ref"], name: "index_squawks_on_external_ref"
|
||||
t.index ["logbook_entry_id"], name: "index_squawks_on_logbook_entry_id"
|
||||
t.index ["reported_by_id"], name: "index_squawks_on_reported_by_id"
|
||||
end
|
||||
@@ -843,6 +874,32 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do
|
||||
t.index ["sso_uid"], name: "index_users_on_sso_uid", unique: true
|
||||
end
|
||||
|
||||
create_table "webhook_deliveries", force: :cascade do |t|
|
||||
t.integer "webhook_endpoint_id", null: false
|
||||
t.string "event", null: false
|
||||
t.text "payload", null: false
|
||||
t.string "status", default: "pending", null: false
|
||||
t.integer "attempts", default: 0, null: false
|
||||
t.integer "response_status"
|
||||
t.string "last_error"
|
||||
t.datetime "delivered_at"
|
||||
t.datetime "created_at", null: false
|
||||
t.datetime "updated_at", null: false
|
||||
t.index ["webhook_endpoint_id", "created_at"], name: "index_webhook_deliveries_on_webhook_endpoint_id_and_created_at"
|
||||
t.index ["webhook_endpoint_id"], name: "index_webhook_deliveries_on_webhook_endpoint_id"
|
||||
end
|
||||
|
||||
create_table "webhook_endpoints", force: :cascade do |t|
|
||||
t.integer "api_token_id", null: false
|
||||
t.string "url", null: false
|
||||
t.text "secret", null: false
|
||||
t.json "events", default: [], null: false
|
||||
t.boolean "enabled", default: true, null: false
|
||||
t.datetime "created_at", null: false
|
||||
t.datetime "updated_at", null: false
|
||||
t.index ["api_token_id"], name: "index_webhook_endpoints_on_api_token_id"
|
||||
end
|
||||
|
||||
create_table "weight_balance_records", force: :cascade do |t|
|
||||
t.integer "aircraft_id", null: false
|
||||
t.date "date", null: false
|
||||
@@ -884,6 +941,8 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do
|
||||
add_foreign_key "aircraft_roles", "users"
|
||||
add_foreign_key "airport_updates", "users", column: "requested_by_id", on_delete: :nullify
|
||||
add_foreign_key "airworthiness_directives", "documents", on_delete: :nullify
|
||||
add_foreign_key "api_idempotency_keys", "api_tokens"
|
||||
add_foreign_key "api_tokens", "users"
|
||||
add_foreign_key "audit_runs", "users", column: "performed_by_id", on_delete: :nullify
|
||||
add_foreign_key "components", "aircraft"
|
||||
add_foreign_key "components", "component_types"
|
||||
@@ -935,6 +994,8 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do
|
||||
add_foreign_key "squawks", "logbook_entries", on_delete: :nullify
|
||||
add_foreign_key "squawks", "users", column: "reported_by_id", on_delete: :nullify
|
||||
add_foreign_key "user_certificates", "users"
|
||||
add_foreign_key "webhook_deliveries", "webhook_endpoints"
|
||||
add_foreign_key "webhook_endpoints", "api_tokens"
|
||||
add_foreign_key "weight_balance_records", "aircraft"
|
||||
add_foreign_key "weight_balance_records", "documents", on_delete: :nullify
|
||||
add_foreign_key "weight_balance_records", "major_records", on_delete: :nullify
|
||||
|
||||
@@ -29,6 +29,7 @@ The same pages are in the app under **Help** in the menu.
|
||||
## Administrators
|
||||
|
||||
- [Administration](administration.md): users, settings, templates, backups and off-site backup to Google Drive, recordkeeping procedures and audits
|
||||
- [REST API](api.md): tokens, endpoints and webhooks, for scripts and other systems such as Redmine
|
||||
|
||||
## Legal
|
||||
|
||||
|
||||
@@ -0,0 +1,125 @@
|
||||
# REST API
|
||||
|
||||
Other programs can work with the aircraft through the API: a script that pulls what's coming due, or another system such as Redmine that tracks work orders. The API reads the same records you see in the app and goes through the same rules. Anything it changes is in the record history, with the person it was for.
|
||||
|
||||
The API never signs a logbook entry, never changes or deletes a signed one, and never changes users, roles or the record history. Signing always happens in the app, by the person certifying the work ([Electronic records and signing](records.md)).
|
||||
|
||||
## Tokens
|
||||
|
||||
Each request carries a token:
|
||||
|
||||
```
|
||||
Authorization: Bearer sam_…
|
||||
```
|
||||
|
||||
There are two kinds:
|
||||
|
||||
| Kind | Made in | Acts as | Reaches |
|
||||
|---|---|---|---|
|
||||
| **Personal** | Profile → API tokens | you | your aircraft, with your role |
|
||||
| **Integration** | Admin → Integrations (administrators) | the person named in `SAM-On-Behalf-Of` | the aircraft chosen for it, and only those that person can also see |
|
||||
|
||||
A token is shown once, when it's made; only its first characters are kept, to tell tokens apart. Revoke a token you no longer need, or one that may have been seen by someone else. Profile and Admin → Integrations show when each token was last used, and from where.
|
||||
|
||||
An integration acting for someone names them by email in each request:
|
||||
|
||||
```
|
||||
SAM-On-Behalf-Of: mechanic@example.com
|
||||
```
|
||||
|
||||
Reading works without it (limited to the integration's aircraft). Every write needs it, so each change names a person.
|
||||
|
||||
### Scopes
|
||||
|
||||
| Scope | Allows |
|
||||
|---|---|
|
||||
| `read` | Aircraft, parts, due items, inspections, ADs, squawks and logbook entries |
|
||||
| `squawks:write` | Reporting squawks and updating them |
|
||||
|
||||
## Requests and answers
|
||||
|
||||
- Base address: `https://<your server>/api/v1`
|
||||
- JSON in and out. Times are ISO 8601 in UTC, hours are decimals, and values are codes (`ENG`, `IN-USE`) rather than translated labels.
|
||||
- Lists answer `{ "data": [ … ], "next_after": 123 }`. Ask for more with `?after=123`; `?limit=` sets the page size (up to 200, default 50); `?updated_since=2026-11-01T00:00:00Z` lists only what changed since then.
|
||||
- Errors answer `{ "error": { "code": "invalid", "message": "…", "fields": { "issue_reported": ["can't be blank"] } } }` with the matching HTTP status: 400 bad request, 401 no or wrong token, 403 not allowed (`missing_scope`, `owners_only`), 404 not found or not reachable with this token, 409 `idempotency_conflict`, 422 invalid, 429 too many requests (600 a minute per token).
|
||||
|
||||
### Safe retries
|
||||
|
||||
Send an `Idempotency-Key` header (any unique string up to 100 characters) with each write. If the answer is lost and you send the same request with the same key again, you get the first answer back (with `Idempotent-Replay: true`) instead of a second record. Keys are kept for 24 hours. The same key with a different request is refused (409).
|
||||
|
||||
### Linking to the other system
|
||||
|
||||
Squawks have an `external_ref`: your own id for them, such as `redmine:issue:4512`. Set it when reporting or later, and find squawks by it with `GET /squawks?external_ref=…`. The other system then doesn't need to store SAM's ids.
|
||||
|
||||
## Endpoints
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| `GET /me` | The token, who it acts as, and the aircraft it reaches |
|
||||
| `GET /aircraft` | The aircraft: tail number, make and model, status, airworthiness, hours |
|
||||
| `GET /aircraft/:id` | One aircraft |
|
||||
| `GET /aircraft/:id/components` | Its parts: type, serial, hours, since overhaul, TBO and replacement limits, parent part (`?all=1` includes disposed parts) |
|
||||
| `GET /aircraft/:id/due` | Everything coming due, soonest first; items due by hours get a projected date |
|
||||
| `GET /aircraft/:id/inspections` | Each inspection's status and next due date and hours |
|
||||
| `GET /aircraft/:id/ads` | Each AD's status and next due date and hours |
|
||||
| `GET /aircraft/:id/logbook_entries` | Logbook entries, with their signatures (`?log=AC`, `ENG`, `PROP` or `OTHER`; `?signed=true` or `false`) |
|
||||
| `GET /aircraft/:id/squawks` | Squawks (`?status=open`, the default, or `resolved` or `all`) |
|
||||
| `POST /aircraft/:id/squawks` | Report a squawk |
|
||||
| `GET /squawks?external_ref=…` | Find squawks by your id for them |
|
||||
| `GET /squawks/:id` | One squawk |
|
||||
| `PATCH /squawks/:id` | Update a squawk |
|
||||
|
||||
### Reporting a squawk
|
||||
|
||||
```
|
||||
POST /api/v1/aircraft/12/squawks
|
||||
Authorization: Bearer sam_…
|
||||
SAM-On-Behalf-Of: pilot@example.com
|
||||
Idempotency-Key: 7f9c1e2a-…
|
||||
Content-Type: application/json
|
||||
|
||||
{ "squawk": { "issue_reported": "Left mag drop 200 rpm", "priority": 0, "component_id": 41, "external_ref": "redmine:issue:4512" } }
|
||||
```
|
||||
|
||||
`priority` is 0 (ground the aircraft), 1 (fix soon), 2 (fix at the next inspection, the default) or 3 (fix eventually). Like a squawk reported in the app, a grounding squawk notifies the aircraft's other people. Anyone who may report squawks on the aircraft can report one.
|
||||
|
||||
The answer is `201` with the squawk:
|
||||
|
||||
```json
|
||||
{ "data": { "id": 88, "aircraft_id": 12, "component_id": 41, "issue_reported": "Left mag drop 200 rpm", "priority": 0,
|
||||
"grounding": true, "deferred": false, "resolved": false, "external_ref": "redmine:issue:4512", … } }
|
||||
```
|
||||
|
||||
### Updating a squawk
|
||||
|
||||
`PATCH /squawks/:id` with `{ "squawk": { … } }`. Anyone who may write can set `external_ref`; changing `issue_reported`, `priority`, `component_id` or `notes` needs an owner of the aircraft, as in the app. A resolved squawk can't be changed. Squawks are resolved by a signed logbook entry, in the app.
|
||||
|
||||
## Webhooks
|
||||
|
||||
An integration can be told about changes. In Admin → Integrations, give it a webhook address and choose the events. SAM then posts JSON there after each change:
|
||||
|
||||
| Event | When |
|
||||
|---|---|
|
||||
| `squawk.created` | A squawk is reported |
|
||||
| `squawk.updated` | A squawk is changed |
|
||||
| `squawk.resolved` | A squawk is resolved |
|
||||
| `entry.signed` | A logbook entry is signed |
|
||||
|
||||
Only events on the integration's aircraft are sent. The body:
|
||||
|
||||
```json
|
||||
{ "event": "squawk.created", "id": "6c1f…", "created_at": "2026-11-20T15:04:05Z", "aircraft_id": 12,
|
||||
"data": { …the squawk, as the API returns it… } }
|
||||
```
|
||||
|
||||
With the headers `SAM-Event`, `SAM-Delivery` (a number, the same on every retry) and `SAM-Signature: t=<unix time>,v1=<signature>`. Check each post before trusting it: compute the HMAC-SHA256 of `<t>.<body>` with the webhook secret (shown once when the webhook is set up; Admin → Integrations → New secret makes another) and compare it with `v1`. Reject posts whose `t` is more than a few minutes old.
|
||||
|
||||
```ruby
|
||||
t, v1 = request.headers["SAM-Signature"].scan(/t=(\d+),v1=(\h+)/).first
|
||||
expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{t}.#{request.raw_post}")
|
||||
valid = ActiveSupport::SecurityUtils.secure_compare(expected, v1.to_s) && (Time.now.to_i - t.to_i).abs < 300
|
||||
```
|
||||
|
||||
Answer any 2xx status to accept it. Anything else, or no answer within 10 seconds, is retried with growing waits (8 tries over about a day), then marked failed. Admin → Integrations lists recent webhooks and what the other system answered. The same event may arrive more than once; use `SAM-Delivery` or the event's `id` to ignore repeats.
|
||||
|
||||
A webhook address may be on your private network (where Redmine often runs), but never the server itself or a link-local address.
|
||||
@@ -0,0 +1,103 @@
|
||||
require "test_helper"
|
||||
|
||||
# Making and revoking API tokens: personal ones on Profile, integrations
|
||||
# (with their webhooks) under Admin.
|
||||
class ApiManagementTest < ActionDispatch::IntegrationTest
|
||||
setup do
|
||||
@admin = create_user("admin@example.com", admin: true)
|
||||
@pilot = create_user("pilot@example.com")
|
||||
@a = create_aircraft(owner: @admin, pilot: @pilot, tail_number: "N12345")
|
||||
end
|
||||
|
||||
test "a personal token is shown once, listed by its first characters, and can be revoked" do
|
||||
sign_in @pilot
|
||||
get edit_profile_path
|
||||
assert_select "#api form[action='#{api_tokens_path}']"
|
||||
post api_tokens_path, params: { api_token: { name: "My script", scopes: %w[read squawks:write bogus] } }
|
||||
assert_response :success
|
||||
token = @pilot.api_tokens.last
|
||||
shown = css_select("input[readonly]").first["value"]
|
||||
assert_equal token, ApiToken.authenticate(shown)
|
||||
assert_equal %w[read squawks:write], token.scopes
|
||||
|
||||
get edit_profile_path
|
||||
assert_select "#api", text: /My script/
|
||||
assert_no_match shown, response.body, "not shown again"
|
||||
delete api_token_path(token)
|
||||
assert token.reload.revoked?
|
||||
assert_nil ApiToken.authenticate(shown)
|
||||
end
|
||||
|
||||
test "you can't revoke someone else's token" do
|
||||
other = ApiToken.create!(name: "theirs", kind: "personal", user: @admin, scopes: %w[read])
|
||||
sign_in @pilot
|
||||
delete api_token_path(other)
|
||||
assert_response :not_found
|
||||
assert_not other.reload.revoked?
|
||||
end
|
||||
|
||||
test "an admin makes an integration with a webhook; the token and secret are shown once" do
|
||||
sign_in @admin
|
||||
get admin_integrations_path
|
||||
assert_response :success
|
||||
post admin_integrations_path, params: { api_token: { name: "Redmine", scopes: %w[read squawks:write], aircraft_ids: [ @a.id ] },
|
||||
webhook: { url: "https://redmine.example.com/sam", events: %w[squawk.created entry.signed] } }
|
||||
assert_response :success
|
||||
integration = ApiToken.integration.last
|
||||
assert_equal [ "Redmine", [ @a.id ], @admin ], [ integration.name, integration.aircraft_ids, integration.user ]
|
||||
token, secret = css_select("input[readonly]").map { _1["value"] }
|
||||
assert_equal integration, ApiToken.authenticate(token)
|
||||
endpoint = integration.webhook_endpoints.sole
|
||||
assert_equal [ secret, %w[squawk.created entry.signed] ], [ endpoint.secret, endpoint.events ]
|
||||
|
||||
get admin_integration_path(integration)
|
||||
assert_response :success
|
||||
assert_no_match token, response.body
|
||||
assert_no_match secret, response.body
|
||||
end
|
||||
|
||||
test "editing an integration changes its reach and webhook; a new secret replaces the old" do
|
||||
integration = ApiToken.create!(name: "Redmine", kind: "integration", user: @admin, scopes: %w[read], aircraft_ids: [])
|
||||
sign_in @admin
|
||||
patch admin_integration_path(integration), params: { api_token: { name: "Redmine", scopes: %w[read], aircraft_ids: [ @a.id ] },
|
||||
webhook: { url: "https://redmine.example.com/sam", events: %w[squawk.resolved] } }
|
||||
assert_redirected_to admin_integration_path(integration)
|
||||
assert_equal [ @a.id ], integration.reload.aircraft_ids
|
||||
old = integration.webhook_endpoints.sole.secret
|
||||
post new_secret_admin_integration_path(integration)
|
||||
assert_not_equal old, integration.webhook_endpoints.sole.reload.secret
|
||||
patch admin_integration_path(integration), params: { api_token: { name: "Redmine", scopes: %w[read], aircraft_ids: [ @a.id ] }, webhook: { url: "" } }
|
||||
assert_empty integration.webhook_endpoints.reload, "clearing the address removes the webhook"
|
||||
end
|
||||
|
||||
test "an invalid integration shows the form again" do
|
||||
sign_in @admin
|
||||
post admin_integrations_path, params: { api_token: { name: "", scopes: [] }, webhook: { url: "not a url", events: [] } }
|
||||
assert_response :unprocessable_entity
|
||||
assert_equal 0, ApiToken.count
|
||||
end
|
||||
|
||||
test "revoking an integration stops its token and webhook" do
|
||||
integration = ApiToken.create!(name: "Redmine", kind: "integration", user: @admin, scopes: %w[read], aircraft_ids: [ @a.id ])
|
||||
endpoint = integration.webhook_endpoints.create!(url: "https://redmine.example.com/", secret: "s" * 32, events: %w[squawk.created])
|
||||
sign_in @admin
|
||||
delete admin_integration_path(integration)
|
||||
assert integration.reload.revoked?
|
||||
assert_not endpoint.reload.enabled
|
||||
end
|
||||
|
||||
test "integrations are for admins only" do
|
||||
sign_in @pilot
|
||||
get admin_integrations_path
|
||||
assert_redirected_to root_path
|
||||
post admin_integrations_path, params: { api_token: { name: "x", scopes: %w[read] } }
|
||||
assert_equal 0, ApiToken.count
|
||||
end
|
||||
|
||||
test "the API reference is in the user guide" do
|
||||
sign_in @pilot
|
||||
get help_page_path("api")
|
||||
assert_response :success
|
||||
assert_select "h1", "REST API"
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,198 @@
|
||||
require "test_helper"
|
||||
|
||||
# The REST API (docs/api.md): tokens, what each kind may reach, the read
|
||||
# endpoints, squawk writes, idempotent retries and webhooks.
|
||||
class ApiTest < ActionDispatch::IntegrationTest
|
||||
setup do
|
||||
@admin = create_user("admin@example.com", admin: true)
|
||||
@owner = create_user("owner@example.com")
|
||||
@pilot = create_user("pilot@example.com")
|
||||
@outsider = create_user("outsider@example.com")
|
||||
@a = create_aircraft(owner: @owner, pilot: @pilot, tail_number: "N12345")
|
||||
@other = create_aircraft(owner: @outsider, tail_number: "N99999")
|
||||
end
|
||||
|
||||
test "no token, a wrong one or a revoked one is refused" do
|
||||
get "/api/v1/me"
|
||||
assert_response :unauthorized
|
||||
get "/api/v1/me", headers: bearer("sam_nope")
|
||||
assert_response :unauthorized
|
||||
token = personal(@pilot)
|
||||
token.revoke!
|
||||
get "/api/v1/me", headers: bearer(token.token)
|
||||
assert_response :unauthorized
|
||||
end
|
||||
|
||||
test "a personal token acts as its owner and reaches exactly their aircraft" do
|
||||
token = personal(@pilot)
|
||||
get "/api/v1/me", headers: bearer(token.token)
|
||||
assert_response :success
|
||||
assert_equal "pilot@example.com", body.dig("data", "acting_as", "email")
|
||||
get "/api/v1/aircraft", headers: bearer(token.token)
|
||||
assert_equal [ "N12345" ], body["data"].map { _1["tail_number"] }
|
||||
get "/api/v1/aircraft/#{@other.id}", headers: bearer(token.token)
|
||||
assert_response :not_found
|
||||
assert token.reload.last_used_at, "last use is recorded"
|
||||
end
|
||||
|
||||
test "a disabled user's token stops working" do
|
||||
token = personal(@pilot)
|
||||
@pilot.update_column(:disabled_at, Time.current)
|
||||
get "/api/v1/me", headers: bearer(token.token)
|
||||
assert_response :unauthorized
|
||||
end
|
||||
|
||||
test "an integration reaches only its aircraft, narrowed to the person it acts for" do
|
||||
token = integration(aircraft: [ @a, @other ])
|
||||
get "/api/v1/aircraft", headers: bearer(token.token)
|
||||
assert_equal %w[N12345 N99999], body["data"].map { _1["tail_number"] }.sort
|
||||
get "/api/v1/aircraft", headers: bearer(token.token, as: @pilot)
|
||||
assert_equal [ "N12345" ], body["data"].map { _1["tail_number"] }
|
||||
get "/api/v1/aircraft", headers: bearer(token.token, as: "nobody@example.com")
|
||||
assert_response :unprocessable_entity
|
||||
assert_equal "unknown_user", body.dig("error", "code")
|
||||
assert_raises(ActiveRecord::RecordInvalid) { ApiToken.create!(name: "x", kind: "integration", user: @owner, scopes: %w[read]) }
|
||||
end
|
||||
|
||||
test "the read endpoints describe the aircraft, its parts, what's due, squawks and entries" do
|
||||
engine = @a.components.create!(component_type: ComponentType.create!(name: "Engine"), manufacturer: "Lycoming", model: "O-320",
|
||||
serial_number: "L-1", date_in_service: Date.new(2020, 1, 1), hours_in_service: 100, tbo_hours: 2000)
|
||||
@a.squawks.create!(issue_reported: "Left brake soft", priority: 1, reported_by: @pilot, external_ref: "redmine:issue:1")
|
||||
@a.logbook_entries.create!(date: Date.current, log_type: "ENG", entry_type: "MAINTENANCE", text: "Oil changed")
|
||||
h = bearer(personal(@owner).token)
|
||||
|
||||
get "/api/v1/aircraft/#{@a.id}", headers: h
|
||||
assert_equal "N12345", body.dig("data", "tail_number")
|
||||
assert body.dig("data", "airworthiness", "status")
|
||||
get "/api/v1/aircraft/#{@a.id}/components", headers: h
|
||||
assert_equal [ [ engine.id, "Engine", "L-1", 2000 ] ], body["data"].map { [ _1["id"], _1["type"], _1["serial_number"], _1.dig("tbo", "hours") ] }
|
||||
get "/api/v1/aircraft/#{@a.id}/due", headers: h
|
||||
assert_kind_of Array, body["data"]
|
||||
get "/api/v1/aircraft/#{@a.id}/squawks", headers: h
|
||||
assert_equal [ "Left brake soft" ], body["data"].map { _1["issue_reported"] }
|
||||
get "/api/v1/squawks", params: { external_ref: "redmine:issue:1" }, headers: h
|
||||
assert_equal 1, body["data"].size
|
||||
get "/api/v1/aircraft/#{@a.id}/logbook_entries", params: { log: "ENG" }, headers: h
|
||||
assert_equal [ [ "Oil changed", false ] ], body["data"].map { [ _1["text"], _1["signed"] ] }
|
||||
get "/api/v1/aircraft/#{@a.id}/inspections", headers: h
|
||||
assert_response :success
|
||||
get "/api/v1/aircraft/#{@a.id}/ads", headers: h
|
||||
assert_response :success
|
||||
end
|
||||
|
||||
test "lists page with after and limit" do
|
||||
5.times { |i| @a.squawks.create!(issue_reported: "Issue #{i}", priority: 2) }
|
||||
h = bearer(personal(@owner).token)
|
||||
get "/api/v1/aircraft/#{@a.id}/squawks", params: { limit: 2 }, headers: h
|
||||
first = body
|
||||
assert_equal 2, first["data"].size
|
||||
get "/api/v1/aircraft/#{@a.id}/squawks", params: { limit: 2, after: first["next_after"] }, headers: h
|
||||
assert_equal 2, body["data"].size
|
||||
assert_empty first["data"].map { _1["id"] } & body["data"].map { _1["id"] }
|
||||
end
|
||||
|
||||
test "a pilot can report a squawk; it's announced and attributed to them, via the token" do
|
||||
token = personal(@pilot)
|
||||
post "/api/v1/aircraft/#{@a.id}/squawks", params: { squawk: { issue_reported: "Mag drop 200 rpm", priority: 0, external_ref: "redmine:issue:9" } },
|
||||
headers: bearer(token.token), as: :json
|
||||
assert_response :created
|
||||
squawk = Squawk.find(body.dig("data", "id"))
|
||||
assert_equal [ @pilot, true, "redmine:issue:9" ], [ squawk.reported_by, squawk.grounding?, squawk.external_ref ]
|
||||
version = squawk.versions.last
|
||||
assert_equal [ @pilot.id, token.id ], [ version.user_id, version.api_token_id ]
|
||||
assert_equal token.id, JSON.parse(version.payload)["api_token_id"], "in the hashed payload"
|
||||
assert @a.events.exists?(category: "squawk")
|
||||
end
|
||||
|
||||
test "integration writes must say who they're for, and need the write scope" do
|
||||
reader = integration(aircraft: [ @a ], scopes: %w[read])
|
||||
writer = integration(aircraft: [ @a ], scopes: %w[read squawks:write])
|
||||
params = { squawk: { issue_reported: "Oil leak" } }
|
||||
post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: bearer(writer.token), as: :json
|
||||
assert_equal "on_behalf_of_required", body.dig("error", "code")
|
||||
post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: bearer(reader.token, as: @pilot), as: :json
|
||||
assert_equal "missing_scope", body.dig("error", "code")
|
||||
post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: bearer(writer.token, as: @outsider), as: :json
|
||||
assert_response :not_found, "the person must have access to the aircraft"
|
||||
post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: bearer(writer.token, as: @pilot), as: :json
|
||||
assert_response :created
|
||||
end
|
||||
|
||||
test "only owners change a squawk's details; anyone who may write can set its external_ref" do
|
||||
squawk = @a.squawks.create!(issue_reported: "Light out", priority: 2)
|
||||
pilot_h = bearer(personal(@pilot).token)
|
||||
patch "/api/v1/squawks/#{squawk.id}", params: { squawk: { priority: 0 } }, headers: pilot_h, as: :json
|
||||
assert_response :forbidden
|
||||
patch "/api/v1/squawks/#{squawk.id}", params: { squawk: { external_ref: "redmine:issue:7" } }, headers: pilot_h, as: :json
|
||||
assert_response :success
|
||||
patch "/api/v1/squawks/#{squawk.id}", params: { squawk: { priority: 1, notes: "Bulb ordered" } }, headers: bearer(personal(@owner).token), as: :json
|
||||
assert_equal [ 1, "Bulb ordered", "redmine:issue:7" ], squawk.reload.then { [ _1.priority, _1.notes, _1.external_ref ] }
|
||||
end
|
||||
|
||||
test "a retry with the same Idempotency-Key gets the first answer, not a second squawk" do
|
||||
h = bearer(personal(@pilot).token).merge("Idempotency-Key" => "abc-123")
|
||||
params = { squawk: { issue_reported: "Door seal torn" } }
|
||||
post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: h, as: :json
|
||||
first = body.dig("data", "id")
|
||||
post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: h, as: :json
|
||||
assert_equal [ first, "true" ], [ body.dig("data", "id"), response.headers["Idempotent-Replay"] ]
|
||||
assert_equal 1, @a.squawks.count
|
||||
post "/api/v1/aircraft/#{@a.id}/squawks", params: { squawk: { issue_reported: "Different" } }, headers: h, as: :json
|
||||
assert_response :conflict
|
||||
end
|
||||
|
||||
test "errors are JSON with the fields at fault" do
|
||||
post "/api/v1/aircraft/#{@a.id}/squawks", params: { squawk: { issue_reported: "" } }, headers: bearer(personal(@pilot).token), as: :json
|
||||
assert_response :unprocessable_entity
|
||||
assert_equal "invalid", body.dig("error", "code")
|
||||
assert body.dig("error", "fields", "issue_reported")
|
||||
post "/api/v1/aircraft/#{@a.id}/squawks", params: "{not json", headers: bearer(personal(@pilot).token).merge("Content-Type" => "application/json")
|
||||
assert_response :bad_request
|
||||
end
|
||||
|
||||
test "webhooks go to integrations that reach the aircraft, signed with their secret" do
|
||||
token = integration(aircraft: [ @a ])
|
||||
endpoint = token.webhook_endpoints.create!(url: "https://hooks.example.com/sam", secret: "s" * 32, events: %w[squawk.created squawk.resolved])
|
||||
other = integration(aircraft: [ @other ]).webhook_endpoints.create!(url: "https://elsewhere.example.com/", secret: "t" * 32, events: %w[squawk.created])
|
||||
stub_request(:post, "https://hooks.example.com/sam").to_return(status: 204)
|
||||
|
||||
perform_enqueued_jobs { @a.squawks.create!(issue_reported: "Prop nick", priority: 1) }
|
||||
assert_requested(:post, "https://hooks.example.com/sam") do |req|
|
||||
t, sig = req.headers["Sam-Signature"].scan(/t=(\d+),v1=(\h+)/).first
|
||||
sig == OpenSSL::HMAC.hexdigest("SHA256", "s" * 32, "#{t}.#{req.body}") && JSON.parse(req.body)["event"] == "squawk.created"
|
||||
end
|
||||
assert_equal [ "delivered", 204 ], endpoint.deliveries.last.then { [ _1.status, _1.response_status ] }
|
||||
assert_empty other.deliveries, "not for an integration that doesn't reach the aircraft"
|
||||
end
|
||||
|
||||
test "a failing webhook is retried, then marked failed" do
|
||||
endpoint = integration(aircraft: [ @a ]).webhook_endpoints.create!(url: "https://hooks.example.com/sam", secret: "s" * 32, events: %w[squawk.created])
|
||||
stub_request(:post, "https://hooks.example.com/sam").to_return(status: 500)
|
||||
perform_enqueued_jobs { @a.squawks.create!(issue_reported: "Tire worn", priority: 2) }
|
||||
delivery = endpoint.deliveries.last
|
||||
assert_equal [ "failed", WebhookDeliveryJob::ATTEMPTS ], [ delivery.status, delivery.attempts ]
|
||||
end
|
||||
|
||||
test "a webhook pointed at the server itself is never sent" do
|
||||
endpoint = integration(aircraft: [ @a ]).webhook_endpoints.create!(url: "http://127.0.0.1:3000/hook", secret: "s" * 32, events: %w[squawk.created])
|
||||
perform_enqueued_jobs { @a.squawks.create!(issue_reported: "Seat rail", priority: 2) }
|
||||
assert_equal "failed", endpoint.deliveries.last.status
|
||||
assert_not_requested :post, "http://127.0.0.1:3000/hook"
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
def personal(user) = ApiToken.create!(name: "script", kind: "personal", user: user, scopes: %w[read squawks:write])
|
||||
|
||||
def integration(aircraft:, scopes: %w[read squawks:write])
|
||||
ApiToken.create!(name: "Redmine", kind: "integration", user: @admin, scopes: scopes, aircraft_ids: aircraft.map(&:id))
|
||||
end
|
||||
|
||||
def bearer(token, as: nil)
|
||||
{ "Authorization" => "Bearer #{token}" }.tap do |h|
|
||||
h["SAM-On-Behalf-Of"] = as.respond_to?(:email_address) ? as.email_address : as if as
|
||||
end
|
||||
end
|
||||
|
||||
def body = JSON.parse(response.body)
|
||||
end
|
||||
@@ -57,11 +57,11 @@ class InternetExposureTest < ActionDispatch::IntegrationTest
|
||||
private
|
||||
|
||||
def resolving_to(*ips)
|
||||
old = AirTrailClient.resolver
|
||||
AirTrailClient.resolver = ->(_) { ips }
|
||||
old = OutboundAddress.resolver
|
||||
OutboundAddress.resolver = ->(_) { ips }
|
||||
yield
|
||||
ensure
|
||||
AirTrailClient.resolver = old
|
||||
OutboundAddress.resolver = old
|
||||
end
|
||||
|
||||
def with_env(vars)
|
||||
|
||||
+1
-1
@@ -6,7 +6,7 @@ WebMock.disable_net_connect!(allow_localhost: true)
|
||||
Dir[File.expand_path("support/**/*.rb", __dir__)].each { require _1 }
|
||||
PwnedPasswords.checker = ->(password) { password == "breached-password-1" } # no network in tests
|
||||
# No DNS in tests: names resolve to a public address, IP addresses to themselves.
|
||||
AirTrailClient.resolver = ->(host) { host.match?(/\A[\d.]+\z|:/) ? [ host.delete("[]") ] : [ "203.0.113.10" ] }
|
||||
OutboundAddress.resolver = ->(host) { host.match?(/\A[\d.]+\z|:/) ? [ host.delete("[]") ] : [ "203.0.113.10" ] }
|
||||
|
||||
module ActiveSupport
|
||||
class TestCase
|
||||
|
||||
Reference in new issue
Block a user