Module: AtlasRb::FaradayHelper

Included in:
Admin::Collection, Admin::Community, Admin::Work, Authentication, Reset, Resource, System::User
Defined in:
lib/atlas_rb/faraday_helper.rb

Overview

HTTP transport helpers shared by every resource class.

Every Atlas request reads two environment variables:

  • ATLAS_URL — base URL of the Atlas API (e.g. https://atlas.example.edu).
  • ATLAS_TOKEN — bearer token used in the Authorization header.

Most calls also identify the acting user via a User: NUID <nuid> header, and optionally an On-Behalf-Of: NUID <nuid> header for acting-as / view-as flows. When nuid / on_behalf_of are omitted (positional arg nil, kwarg nil), the helper falls through to config's default_nuid / default_on_behalf_of callables — host applications wire those up to their request-scoped Current.* source. Caller-passed values always win over the configured defaults.

The module is mixed in via extend, so its methods become class methods on the host (e.g. AtlasRb::Work.connection({})).

Instance Method Summary collapse

Instance Method Details

#connection(params, nuid = nil, on_behalf_of: nil, idempotency_key: nil) ⇒ Faraday::Connection

Build a JSON-content Faraday connection to the Atlas API.

Examples:

Fetching a community

AtlasRb::Community.connection({}).get('/communities/abc123')

Parameters:

  • params (Hash) —

    query-string / body params to attach to the request. Resource classes use this to pass things like parent_id:, work_id:, or metadata: without manually serializing.

  • nuid (String, nil) (defaults to: nil) —

    optional Northeastern University ID to send in the User header. When nil, falls through to AtlasRb.config.default_nuid&.call; if that is also nil, no User: header is sent (legacy bearer-only path).

  • on_behalf_of (String, nil) (defaults to: nil) —

    optional NUID for the On-Behalf-Of header. When nil, falls through to AtlasRb.config.default_on_behalf_of&.call; if that is also nil, no On-Behalf-Of: header is sent. Used by acting-as / view-as flows.

  • idempotency_key (String, nil) (defaults to: nil) —

    optional UUID to send in the Idempotency-Key header. Used by retry-safe create flows (currently POST /works, POST /file_sets, POST /files) to deduplicate replays against the originally-created resource. Generated by the caller — this gem does not mint keys.

Returns:

  • (Faraday::Connection) —

    a connection that follows redirects and uses Faraday's default adapter.



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/atlas_rb/faraday_helper.rb', line 45

def connection(params, nuid=nil, on_behalf_of: nil, idempotency_key: nil)
  nuid         ||= AtlasRb.config.default_nuid&.call
  on_behalf_of ||= AtlasRb.config.default_on_behalf_of&.call

  headers = {
    "Content-Type" => "application/json",
    "Authorization" => "Bearer #{ENV.fetch("ATLAS_TOKEN", nil)}"
  }
  headers["User"]            = "NUID #{nuid}" if nuid
  headers["On-Behalf-Of"]    = "NUID #{on_behalf_of}" if on_behalf_of
  headers["Idempotency-Key"] = idempotency_key if idempotency_key

  Faraday.new(
    url: ENV.fetch("ATLAS_URL", nil),
    params: params,
    headers: headers
  ) do |f|
    f.response :follow_redirects
    f.adapter Faraday.default_adapter
  end
end

#multipart(nuid = nil, on_behalf_of: nil, idempotency_key: nil) ⇒ Faraday::Connection

Build a multipart Faraday connection used for binary and XML uploads.

The same ATLAS_URL / ATLAS_TOKEN env vars apply. Unlike #connection, the Content-Type is set automatically by the multipart middleware, and callers pass a payload hash whose values may include Faraday::Multipart::FilePart instances. Fall-through semantics for nuid / on_behalf_of match #connection.

Examples:

Posting a binary blob

payload = {
  work_id: "w-123",
  binary: Faraday::Multipart::FilePart.new(File.open("scan.pdf"),
                                            "application/octet-stream",
                                            "scan.pdf")
}
AtlasRb::Blob.multipart.post('/files/', payload)

Parameters:

  • nuid (String, nil) (defaults to: nil) —

    optional NUID for the User header.

  • on_behalf_of (String, nil) (defaults to: nil) —

    optional NUID for the On-Behalf-Of header.

  • idempotency_key (String, nil) (defaults to: nil) —

    optional UUID to send in the Idempotency-Key header. See #connection for semantics; the POST /files (Blob) create flow uses this transport.

Returns:

  • (Faraday::Connection) —

    a multipart-aware connection.



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/atlas_rb/faraday_helper.rb', line 91

def multipart(nuid=nil, on_behalf_of: nil, idempotency_key: nil)
  nuid         ||= AtlasRb.config.default_nuid&.call
  on_behalf_of ||= AtlasRb.config.default_on_behalf_of&.call

  headers = {
    "Authorization" => "Bearer #{ENV.fetch("ATLAS_TOKEN", nil)}"
  }
  headers["User"]            = "NUID #{nuid}" if nuid
  headers["On-Behalf-Of"]    = "NUID #{on_behalf_of}" if on_behalf_of
  headers["Idempotency-Key"] = idempotency_key if idempotency_key

  Faraday.new(
    url: ENV.fetch("ATLAS_URL", nil),
    headers: headers
  ) do |f|
    f.request :multipart
    f.request :url_encoded
  end
end

#system_connection(params = {}) ⇒ Faraday::Connection

Build a Faraday connection authenticated as the Atlas :system fixture for system-context calls (SSO user provisioning, etc.).

Distinct from #connection. The bearer token comes from Rails.application.credentials.atlas_system_token (NOT ENV — the source report's leak-halving argument: a .env leak shouldn't expose the system token alongside the user token). The User: header is hard-pinned to System::NUID so this path always identifies as the Atlas system principal. The configurable default_nuid / default_on_behalf_of are never consulted — there is no ambient user context on this path.

Used exclusively by classes under System.

Parameters:

  • params (Hash) (defaults to: {}) —

    query-string / body params.

Returns:

  • (Faraday::Connection) —

    a system-authenticated connection.

Raises:

  • (RuntimeError) —

    if the credential is not configured.

  • (NameError) —

    if Rails is not loaded (the gem assumes a Rails host for system-path calls).



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/atlas_rb/faraday_helper.rb', line 130

def system_connection(params = {})
  token = Rails.application.credentials.atlas_system_token ||
          raise("atlas_rb: Rails.application.credentials.atlas_system_token not configured")

  headers = {
    "Content-Type"  => "application/json",
    "Authorization" => "Bearer #{token}",
    "User"          => "NUID #{AtlasRb::System::NUID}"
  }

  Faraday.new(
    url: ENV.fetch("ATLAS_URL", nil),
    params: params,
    headers: headers
  ) do |f|
    f.response :follow_redirects
    f.adapter Faraday.default_adapter
  end
end