Class: Smplkit::Audit::Forwarder

Inherits:
Object
  • Object
show all
Defined in:
lib/smplkit/audit/models.rb

Overview

A SIEM streaming forwarder configured on the customer’s account.

Active-record style: instantiate via client.audit.forwarders.new(…), mutate fields directly, and call #save to persist or #delete to remove. Header values in configuration.headers are returned in plaintext on reads, so fetching a forwarder, mutating it, and calling #save preserves its header values without re-entering secrets.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client = nil, name:, forwarder_type:, configuration:, id: nil, enabled: false, forward_smplkit_events: false, environments: nil, description: nil, filter: nil, transform: nil, transform_type: nil, created_at: nil, updated_at: nil, deleted_at: nil, version: nil) ⇒ Forwarder

Returns a new instance of Forwarder.



538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
 
# File 'lib/smplkit/audit/models.rb', line 538

def initialize(client = nil, name:, forwarder_type:, configuration:,
               id: nil, enabled: false, forward_smplkit_events: false,
               environments: nil, description: nil,
               filter: nil, transform: nil, transform_type: nil,
               created_at: nil, updated_at: nil, deleted_at: nil, version: nil)
  @client = client
  @id = id
  @name = name
  @forwarder_type = ForwarderType.coerce(forwarder_type)
  @configuration = configuration
  # ``enabled`` is server-pinned false; we keep the attribute so reads
  # round-trip the server value, but enablement is driven by
  # ``environments`` (see the class docstring).
  @enabled = enabled
  @forward_smplkit_events = forward_smplkit_events
  @environments = environments || {}
  @description = description
  @filter = filter
  @transform = transform
  @transform_type = TransformType.coerce(transform_type)
  @created_at = created_at
  @updated_at = updated_at
  @deleted_at = deleted_at
  @version = version
end

Instance Attribute Details

#configuration ⇒ HttpConfiguration

Returns Destination request configuration.

Returns:



505
506
507
 
# File 'lib/smplkit/audit/models.rb', line 505

def configuration
  @configuration
end

#created_at ⇒ String?

Returns ISO-8601 timestamp of first persist. nil for an unsaved instance.

Returns:

  • (String, nil) —

    ISO-8601 timestamp of first persist. nil for an unsaved instance.



527
528
529
 
# File 'lib/smplkit/audit/models.rb', line 527

def created_at
  @created_at
end

#deleted_at ⇒ String?

Returns Deletion timestamp; nil for live forwarders.

Returns:

  • (String, nil) —

    Deletion timestamp; nil for live forwarders.



533
534
535
 
# File 'lib/smplkit/audit/models.rb', line 533

def deleted_at
  @deleted_at
end

#description ⇒ String?

Returns Optional free-text description.

Returns:

  • (String, nil) —

    Optional free-text description.



508
509
510
 
# File 'lib/smplkit/audit/models.rb', line 508

def description
  @description
end

#enabled ⇒ Boolean

Returns Read-only. Always false — the base enablement is pinned off. Whether a forwarder actually delivers is decided per environment via #environments; mutating this field has no effect on the server.

Returns:

  • (Boolean) —

    Read-only. Always false — the base enablement is pinned off. Whether a forwarder actually delivers is decided per environment via #environments; mutating this field has no effect on the server.



483
484
485
 
# File 'lib/smplkit/audit/models.rb', line 483

def enabled
  @enabled
end

#environments ⇒ Hash{String => ForwarderEnvironment}

Returns Per-environment overrides keyed by environment key (e.g. “production”, “staging”). A forwarder delivers in an environment only when environments[env].enabled is true. Each entry may carry an optional HttpConfiguration override; omit it to inherit the base #configuration. Every referenced environment must exist and be managed for the account.

Returns:

  • (Hash{String => ForwarderEnvironment}) —

    Per-environment overrides keyed by environment key (e.g. “production”, “staging”). A forwarder delivers in an environment only when environments[env].enabled is true. Each entry may carry an optional HttpConfiguration override; omit it to inherit the base #configuration. Every referenced environment must exist and be managed for the account.



502
503
504
 
# File 'lib/smplkit/audit/models.rb', line 502

def environments
  @environments
end

#filter ⇒ Hash?

Returns Optional JSON Logic expression evaluated per event. When set, events that don’t match are recorded as filtered_out deliveries instead of being delivered to the destination.

Returns:

  • (Hash, nil) —

    Optional JSON Logic expression evaluated per event. When set, events that don’t match are recorded as filtered_out deliveries instead of being delivered to the destination.



513
514
515
 
# File 'lib/smplkit/audit/models.rb', line 513

def filter
  @filter
end

#forward_smplkit_events ⇒ Boolean

Returns When true, this forwarder also receives platform change events that smplkit records about your own resources (flag, configuration, and similar changes). Each such event is delivered through every environment this forwarder is enabled in, using that environment’s resolved configuration. Defaults to false — platform change events are not forwarded unless you opt in. Independent of the per-environment enabled settings, since platform change events are not tied to a deployment environment.

Returns:

  • (Boolean) —

    When true, this forwarder also receives platform change events that smplkit records about your own resources (flag, configuration, and similar changes). Each such event is delivered through every environment this forwarder is enabled in, using that environment’s resolved configuration. Defaults to false — platform change events are not forwarded unless you opt in. Independent of the per-environment enabled settings, since platform change events are not tied to a deployment environment.



493
494
495
 
# File 'lib/smplkit/audit/models.rb', line 493

def forward_smplkit_events
  @forward_smplkit_events
end

#forwarder_type ⇒ String

Returns One of Smplkit::Audit::ForwarderType::VALUES.

Returns:



477
478
479
 
# File 'lib/smplkit/audit/models.rb', line 477

def forwarder_type
  @forwarder_type
end

#id ⇒ String?

Returns Caller-supplied unique identifier (key) for this forwarder. Unique within an account; immutable for the lifetime of the forwarder. nil only while the object represents an unsaved instance constructed without an id (which #save would then reject).

Returns:

  • (String, nil) —

    Caller-supplied unique identifier (key) for this forwarder. Unique within an account; immutable for the lifetime of the forwarder. nil only while the object represents an unsaved instance constructed without an id (which #save would then reject).



471
472
473
 
# File 'lib/smplkit/audit/models.rb', line 471

def id
  @id
end

#name ⇒ String

Returns Display name. Free-form.

Returns:

  • (String) —

    Display name. Free-form.



474
475
476
 
# File 'lib/smplkit/audit/models.rb', line 474

def name
  @name
end

#transform ⇒ Object?

Returns Optional template applied to each event before delivery. Free-form — the audit service passes the value verbatim to the engine named by #transform_type. For TransformType::JSONATA a JSONata expression string; nil delivers the event JSON as-is. Must be paired with a non-nil #transform_type.

Returns:

  • (Object, nil) —

    Optional template applied to each event before delivery. Free-form — the audit service passes the value verbatim to the engine named by #transform_type. For TransformType::JSONATA a JSONata expression string; nil delivers the event JSON as-is. Must be paired with a non-nil #transform_type.



520
521
522
 
# File 'lib/smplkit/audit/models.rb', line 520

def transform
  @transform
end

#transform_type ⇒ String?

Returns Engine that evaluates #transform — one of TransformType::VALUES. Required whenever #transform is set.

Returns:



524
525
526
 
# File 'lib/smplkit/audit/models.rb', line 524

def transform_type
  @transform_type
end

#updated_at ⇒ String?

Returns ISO-8601 timestamp of the most recent mutation.

Returns:

  • (String, nil) —

    ISO-8601 timestamp of the most recent mutation.



530
531
532
 
# File 'lib/smplkit/audit/models.rb', line 530

def updated_at
  @updated_at
end

#version ⇒ Integer?

Returns Monotonic version counter, bumped on every server-side write.

Returns:

  • (Integer, nil) —

    Monotonic version counter, bumped on every server-side write.



536
537
538
 
# File 'lib/smplkit/audit/models.rb', line 536

def version
  @version
end

Class Method Details

.from_resource(resource, client: nil) ⇒ Object 



676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
 
# File 'lib/smplkit/audit/models.rb', line 676

def self.from_resource(resource, client: nil)
  a = resource.attributes
  environments = (a.environments || {}).each_with_object({}) do |(env_key, env_raw), out|
    out[env_key.to_s] = ForwarderEnvironment.from_wire(env_raw)
  end
  new(
    client,
    id: resource.id,
    name: a.name,
    description: a.description,
    forwarder_type: a.forwarder_type,
    # The base ``enabled`` is server-pinned false; round-trip whatever
    # the server returned (always false) without assuming a default of
    # true.
    enabled: a.enabled.nil? ? false : a.enabled,
    # ``forward_smplkit_events`` defaults to false; a forwarder persisted
    # before the field landed reads back as not opted in.
    forward_smplkit_events: a.forward_smplkit_events.nil? ? false : a.forward_smplkit_events,
    environments: environments,
    filter: a.filter.nil? ? nil : Smplkit::Helpers.deep_stringify_keys(a.filter),
    transform_type: a.transform_type,
    transform: a.transform,
    configuration: HttpConfiguration.from_wire(a.configuration),
    created_at: a.created_at,
    updated_at: a.updated_at,
    deleted_at: a.deleted_at,
    version: a.version
  )
end

.validate_transform_pair!(transform, transform_type) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Validate the (transform, transform_type) pair.

Both must be nil or both must be set. When transform_type is TransformType::JSONATA, transform must be a String (the JSONata expression). Other engines accept any value.

Raises:

  • (ArgumentError) 


663
664
665
666
667
668
669
670
671
672
673
674
 
# File 'lib/smplkit/audit/models.rb', line 663

def self.validate_transform_pair!(transform, transform_type)
  if transform.nil? != transform_type.nil?
    raise ArgumentError,
          "transform and transform_type must be specified together (both nil or both set)"
  end
  return if transform.nil?
  return unless transform_type == TransformType::JSONATA && !transform.is_a?(String)

  raise ArgumentError,
        "transform must be a String when transform_type is JSONATA " \
        "(got #{transform.class})"
end

Instance Method Details

#_apply(other) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
 
# File 'lib/smplkit/audit/models.rb', line 638

def _apply(other)
  @id = other.id
  @name = other.name
  @forwarder_type = other.forwarder_type
  @configuration = other.configuration
  @enabled = other.enabled
  @forward_smplkit_events = other.forward_smplkit_events
  @environments = other.environments
  @description = other.description
  @filter = other.filter
  @transform = other.transform
  @transform_type = other.transform_type
  @created_at = other.created_at
  @updated_at = other.updated_at
  @deleted_at = other.deleted_at
  @version = other.version
end

#_environment_override(environment) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return the override for environment, creating an empty one if absent.

The per-environment mutators reach through here so an existing override’s other field is preserved when only one of enabled / configuration is being set.



633
634
635
 
# File 'lib/smplkit/audit/models.rb', line 633

def _environment_override(environment)
  @environments[environment] ||= ForwarderEnvironment.new
end

#delete ⇒ nil Also known as: delete!

Delete this forwarder on the server.

Returns:

  • (nil) 


589
590
591
592
593
 
# File 'lib/smplkit/audit/models.rb', line 589

def delete
  raise "Forwarder was constructed without a client or id; cannot delete" if @client.nil? || @id.nil?

  @client.delete(@id)
end

#save ⇒ self Also known as: save!

Create or update this forwarder on the server.

Upsert behavior is driven by #created_at: a forwarder with no created_at is created (POST); otherwise it’s full-replace updated (PUT). After the call, every field is refreshed from the server response (including newly-assigned id, created_at, updated_at, version).

Returns:

  • (self)

Raises:



576
577
578
579
580
581
582
583
 
# File 'lib/smplkit/audit/models.rb', line 576

def save
  raise "Forwarder was constructed without a client; cannot save" if @client.nil?

  self.class.send(:validate_transform_pair!, @transform, @transform_type)
  updated = @created_at.nil? ? @client._create_forwarder(self) : @client._update_forwarder(self)
  _apply(updated)
  self
end

#set_configuration(configuration, environment: nil) ⇒ Object

Set this forwarder’s destination configuration in memory.

With environment omitted, replaces the base #configuration. With environment given, sets the per-environment override’s configuration on #environments, creating the override entry if it doesn’t exist yet (preserving any already-set enabled on it). Call #save to persist.



602
603
604
605
606
607
608
 
# File 'lib/smplkit/audit/models.rb', line 602

def set_configuration(configuration, environment: nil)
  if environment.nil?
    @configuration = configuration
  else
    _environment_override(environment).configuration = configuration
  end
end

#set_enabled(enabled, environment: nil) ⇒ Object

Set this forwarder’s enablement in memory.

With environment omitted, sets the base #enabled (which the server pins false regardless — enablement is per-environment). With environment given, sets the per-environment override’s enabled on #environments, creating the override entry if it doesn’t exist yet (preserving any already-set configuration on it). Call #save to persist.



618
619
620
621
622
623
624
 
# File 'lib/smplkit/audit/models.rb', line 618

def set_enabled(enabled, environment: nil)
  if environment.nil?
    @enabled = enabled
  else
    _environment_override(environment).enabled = enabled
  end
end