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, 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.



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

def initialize(client = nil, name:, forwarder_type:, configuration:,
               id: nil, 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
  @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:



605
606
607
 
# File 'lib/smplkit/audit/models.rb', line 605

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.



627
628
629
 
# File 'lib/smplkit/audit/models.rb', line 627

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.



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

def deleted_at
  @deleted_at
end

#description ⇒ String?

Returns Optional free-text description.

Returns:

  • (String, nil) —

    Optional free-text description.



608
609
610
 
# File 'lib/smplkit/audit/models.rb', line 608

def description
  @description
end

#environments ⇒ Hash{String => ForwarderEnvironment}

Returns Per-environment sparse overrides keyed by environment key (e.g. “production”, “staging”). A forwarder delivers in an environment only when environments[env].enabled is true. Each entry overrides only the leaves it sets; omitted leaves inherit the base #configuration. Reach one via #environment. Every referenced environment must exist and be managed for the account.

Returns:

  • (Hash{String => ForwarderEnvironment}) —

    Per-environment sparse overrides keyed by environment key (e.g. “production”, “staging”). A forwarder delivers in an environment only when environments[env].enabled is true. Each entry overrides only the leaves it sets; omitted leaves inherit the base #configuration. Reach one via #environment. Every referenced environment must exist and be managed for the account.



602
603
604
 
# File 'lib/smplkit/audit/models.rb', line 602

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.



613
614
615
 
# File 'lib/smplkit/audit/models.rb', line 613

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.



593
594
595
 
# File 'lib/smplkit/audit/models.rb', line 593

def forward_smplkit_events
  @forward_smplkit_events
end

#forwarder_type ⇒ String

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

Returns:



575
576
577
 
# File 'lib/smplkit/audit/models.rb', line 575

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).



569
570
571
 
# File 'lib/smplkit/audit/models.rb', line 569

def id
  @id
end

#name ⇒ String

Returns Display name. Free-form.

Returns:

  • (String) —

    Display name. Free-form.



572
573
574
 
# File 'lib/smplkit/audit/models.rb', line 572

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.



620
621
622
 
# File 'lib/smplkit/audit/models.rb', line 620

def transform
  @transform
end

#transform_type ⇒ String?

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

Returns:



624
625
626
 
# File 'lib/smplkit/audit/models.rb', line 624

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.



630
631
632
 
# File 'lib/smplkit/audit/models.rb', line 630

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.



636
637
638
 
# File 'lib/smplkit/audit/models.rb', line 636

def version
  @version
end

Class Method Details

.from_resource(resource, client: nil) ⇒ Object 



750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
 
# File 'lib/smplkit/audit/models.rb', line 750

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_flat(env_raw)
  end
  new(
    client,
    id: resource.id,
    name: a.name,
    description: a.description,
    forwarder_type: a.forwarder_type,
    # The base ``enabled`` roll-up is derived from ``environments``, not
    # read from the wire — the API has no top-level ``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) 


737
738
739
740
741
742
743
744
745
746
747
748
 
# File 'lib/smplkit/audit/models.rb', line 737

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. 



713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
 
# File 'lib/smplkit/audit/models.rb', line 713

def _apply(other)
  @id = other.id
  @name = other.name
  @forwarder_type = other.forwarder_type
  @configuration = other.configuration
  @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

#delete ⇒ nil Also known as: delete!

Delete this forwarder on the server.

Returns:

  • (nil) 


685
686
687
688
689
 
# File 'lib/smplkit/audit/models.rb', line 685

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

  @client.delete(@id)
end

#enabled ⇒ Boolean

Returns Read-only roll-up: true when the forwarder is enabled in at least one environment. Derived from #environments — there is no server-side top-level enabled field. Enable per environment via forwarder.environment(env).enabled = true.

Returns:

  • (Boolean) —

    Read-only roll-up: true when the forwarder is enabled in at least one environment. Derived from #environments — there is no server-side top-level enabled field. Enable per environment via forwarder.environment(env).enabled = true.



581
582
583
 
# File 'lib/smplkit/audit/models.rb', line 581

def enabled
  (@environments || {}).each_value.any?(&:enabled)
end

#environment(environment) ⇒ ForwarderEnvironment

The per-environment override for environment — the single place to read or set what this forwarder overrides there (ADR-056).

Returns the Smplkit::Audit::ForwarderEnvironment for environment, creating an empty one (and inserting it into #environments) on first access, so you can set overrides directly:

forwarder.environment("production").enabled = true
forwarder.environment("production").url = "https://prod.siem.example.com/in"
forwarder.environment("production").set_header("DD-API-KEY", "prod-secret")

Only the leaves you set are sent on save; everything else inherits the base definition (the server resolves base ⊕ overrides on delivery).

Parameters:

  • environment (String) —

    The environment key.

Returns:



708
709
710
 
# File 'lib/smplkit/audit/models.rb', line 708

def environment(environment)
  @environments[environment] ||= ForwarderEnvironment.new
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:



672
673
674
675
676
677
678
679
 
# File 'lib/smplkit/audit/models.rb', line 672

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