Module: Shojiku::Outcome

Defined in:
lib/shojiku/outcome.rb

Overview

Turning one engine Snapshot into the Result an application sees.

The C surface's two levels of failure meet here, and keeping them apart is the whole job: a non-zero status is the CALLER's mistake and raises, while everything a DOCUMENT can do wrong comes back as a failed result with the engine's diagnostics attached.

Class Method Summary collapse

Class Method Details

.document(snapshot, step:, client:, origin:) ⇒ Object

A rendered or signed document. Diagnostics are attached either way: a render that WORKED can still have warned.



24
25
26
27
28
29
30
 
# File 'lib/shojiku/outcome.rb', line 24

def document(snapshot, step:, client:, origin:)
  guard!(snapshot)
  diagnostics = Diagnostic.parse(snapshot.diagnostics)
  return refused(snapshot, step, diagnostics) unless snapshot.success

  Result.succeeded(artifact(snapshot, diagnostics, client, origin), diagnostics)
end

.guard!(snapshot) ⇒ Object

A non-zero status is the C surface saying the CALLER got it wrong — a null pointer, a request the schema rejects, an argument past a hard cap. That is programmer misuse in Ruby terms, so it raises.

Raises:



15
16
17
18
19
20
 
# File 'lib/shojiku/outcome.rb', line 15

def guard!(snapshot)
  return if snapshot.status.zero?

  raise UsageError,
        "the engine refused the call (status #{snapshot.status}): #{snapshot.error}"
end

.verdict(snapshot) ⇒ Object

A verification verdict.

The report is parsed BEFORE the verdict is read, because it rides a FAILED verify too — that is the whole point of carrying not_checked. Diagnostics are parsed on both paths for the same reason they are on a render: whatever the engine noticed belongs to the caller, and an operation that drops them makes its result mean something different from every other operation's.



40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/shojiku/outcome.rb', line 40

def verdict(snapshot)
  guard!(snapshot)
  diagnostics = Diagnostic.parse(snapshot.diagnostics)
  report = snapshot.json.empty? ? nil : VerificationReport.parse(snapshot.json)
  return Result.succeeded(report, diagnostics) if snapshot.success

  failure = Failure.from_error_json(
    snapshot.error, step: :verify, diagnostics: diagnostics
  )
  Result.new(value: report, diagnostics: diagnostics, failure: failure)
end