Class: Linzer::Message::Overlay

Inherits:
Object
  • Object
show all
Defined in:
lib/linzer/message/overlay.rb

Overview

Overlay provides a signing-time augmentation layer for HTTP headers.

It allows additional headers to be introduced during HTTP Message Signature generation without mutating the underlying HTTP message.

IMPORTANT SEMANTICS

Overlay affects ONLY HTTP header resolution.

It MUST NOT influence derived HTTP Message Signature components such as:

- @method
- @authority
- @target-uri

These values are always computed from the underlying HTTP message.

Resolution rules:

Header lookup:

1. Underlying message headers
2. Overlay headers (fallback only)

Derived components:

Always resolved from the underlying message only

Purpose:

This class exists to support signing-time augmentation of header values (e.g., injected or synthesized headers required by signing profiles) without altering the canonical representation of the HTTP message.

This is NOT a full message override layer. It is a header-only augmentation mechanism used during signing.

DESIGN NOTE: Overlay does not implement full HTTP message semantics. It only participates in header resolution for signing-time evaluation.

Instance Method Summary collapse

Constructor Details

#initialize(message, overlay_headers) ⇒ Overlay

Creates a new overlay message.

Parameters:

  • message (Linzer::Message) —

    The underlying message to wrap

  • overlay_headers (#to_h, Hash) —

    Additional headers to overlay onto the message A hash-like object containing HTTP headers to use as an overlay layer. Keys and values must be compatible with Net::HTTP header semantics.



55
56
57
58
59
60
61
62
 
# File 'lib/linzer/message/overlay.rb', line 55

def initialize(message, overlay_headers)
  @message         = message
  @overlay_headers = overlay_headers

  # Internal adapter-backed overlay used to reuse Linzer's field
  # resolution logic for header/field evaluation.
  @overlay         = build_overlay_message(overlay_headers)
end

Instance Method Details

#[](name) ⇒ Object?

Retrieves a resolved header or field value from the signing-time view.

Resolution order:

1. Underlying HTTP message
2. Overlay headers (fallback only)

IMPORTANT: Overlay values are ONLY used when the underlying message does not provide a value. They do not override existing message values.

Derived HTTP Message Signature components (e.g. @method, @target-uri, @authority) are always resolved exclusively from the underlying message and are never influenced by overlay headers.

Parameters:

Returns:

  • (Object, nil) 


121
122
123
124
125
126
127
 
# File 'lib/linzer/message/overlay.rb', line 121

def [](name)
  value = @message[name]
  return value unless value.nil?

  return nil if Linzer::FieldId.new(field_name: name).derived?
  @overlay[name]
end

#attach!(signature) ⇒ Object

Attaches signature headers to the underlying HTTP message.

Overlay headers are applied only as HTTP headers at attachment time. They do not affect derived HTTP Message Signature components.

Parameters:

Returns:

  • (Object) —

    The underlying message returned by Linzer::Message#attach!



100
101
102
 
# File 'lib/linzer/message/overlay.rb', line 100

def attach!(signature)
  @message.attach!(signature, additional_headers: @overlay_headers.to_h)
end

#field?(field) ⇒ Boolean

Returns true if the field can be resolved from:

  • the underlying HTTP message (including derived fields), or

  • overlay headers (header fields only)

NOTE: Overlay headers do not participate in derived component resolution (e.g. @method, @target-uri, @authority).

Parameters:

Returns:

  • (Boolean) 


88
89
90
 
# File 'lib/linzer/message/overlay.rb', line 88

def field?(field)
  @message.field?(field) || (!field.derived? && @overlay.field?(field))
end

#header(name) ⇒ String?

Returns a header value from the signing-time resolution view.

Overlay headers are only used if the underlying message does not provide a value for the requested header.

Derived components (e.g. @authority, @target-uri) are not affected.

Parameters:

  • name (String)

Returns:

  • (String, nil) 


73
74
75
 
# File 'lib/linzer/message/overlay.rb', line 73

def header(name)
  @message.header(name) || @overlay.header(name)
end