Class: Smplkit::Jobs::Job

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

Overview

A unit of work: an HTTP request, run on a schedule or triggered on demand.

Active-record style: instantiate via client.jobs.new_recurring_job(…), new_manual_job(…), or schedule(…), 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 job, mutating it, and calling #save preserves its header values without re-entering secrets.

A job’s #kind follows from its #schedule: a recurring (cron) job, a manual job (no schedule, runs only when triggered), or a one-off (now / datetime) job that runs a single time. Enablement is per environment, set via #set_enabled (and read via #is_enabled); base #enabled is a derived roll-up over #environments. The base schedule is environment-agnostic, while each environment may carry its own cron #set_schedule override.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client = nil, id:, name:, configuration:, schedule: nil, description: nil, environments: nil, kind: nil, type: "http", concurrency_policy: "ALLOW", birth_environment: nil, created_at: nil, updated_at: nil, deleted_at: nil, version: nil) ⇒ Job

Returns a new instance of Job.



418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
 
# File 'lib/smplkit/jobs/models.rb', line 418

def initialize(client = nil, id:, name:, configuration:, schedule: nil,
               description: nil, environments: nil,
               kind: nil, type: "http", concurrency_policy: "ALLOW",
               birth_environment: nil, created_at: nil,
               updated_at: nil, deleted_at: nil, version: nil)
  @client = client
  @id = id
  @name = name
  @description = description
  @environments = environments || {}
  @kind = kind
  @type = type
  @schedule = schedule
  @configuration = configuration
  @concurrency_policy = concurrency_policy
  @birth_environment = birth_environment
  @created_at = created_at
  @updated_at = updated_at
  @deleted_at = deleted_at
  @version = version
end

Instance Attribute Details

#birth_environment ⇒ Object 



416
417
418
 
# File 'lib/smplkit/jobs/models.rb', line 416

def birth_environment
  @birth_environment
end

#concurrency_policy ⇒ String

Returns How overlapping runs are handled. “ALLOW” (the only value) permits them.

Returns:

  • (String) —

    How overlapping runs are handled. “ALLOW” (the only value) permits them.



395
396
397
 
# File 'lib/smplkit/jobs/models.rb', line 395

def concurrency_policy
  @concurrency_policy
end

#configuration ⇒ HttpConfig

Returns The base HTTP request to perform when the job fires. Per-environment overrides live in #environments.

Returns:

  • (HttpConfig) —

    The base HTTP request to perform when the job fires. Per-environment overrides live in #environments.



391
392
393
 
# File 'lib/smplkit/jobs/models.rb', line 391

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.



399
400
401
 
# File 'lib/smplkit/jobs/models.rb', line 399

def created_at
  @created_at
end

#deleted_at ⇒ String?

Returns Timestamp when the job was deleted; nil for live jobs.

Returns:

  • (String, nil) —

    Timestamp when the job was deleted; nil for live jobs.



406
407
408
 
# File 'lib/smplkit/jobs/models.rb', line 406

def deleted_at
  @deleted_at
end

#description ⇒ String?

Returns Free-text description. nil when unset.

Returns:

  • (String, nil) —

    Free-text description. nil when unset.



353
354
355
 
# File 'lib/smplkit/jobs/models.rb', line 353

def description
  @description
end

#environments ⇒ Hash{String => JobEnvironment}

Returns Per-environment overrides keyed by environment key (e.g. “production”). The writable surface for enablement: a recurring job fires in an environment only when environments[env].enabled is true. Each entry may carry an optional HttpConfig override; omit it to inherit the base #configuration. Every referenced environment must exist and be managed for the account.

Returns:

  • (Hash{String => JobEnvironment}) —

    Per-environment overrides keyed by environment key (e.g. “production”). The writable surface for enablement: a recurring job fires in an environment only when environments[env].enabled is true. Each entry may carry an optional HttpConfig override; omit it to inherit the base #configuration. Every referenced environment must exist and be managed for the account.



369
370
371
 
# File 'lib/smplkit/jobs/models.rb', line 369

def environments
  @environments
end

#id ⇒ String

Caller-supplied unique identifier for the job (the resource id). Unique within the account and immutable; the service returns 409 if another live job already uses this id.

Returns:

  • (String) —

    Caller-supplied unique identifier for the job (the resource id). Unique within the account and immutable; the service returns 409 if another live job already uses this id.



347
348
349
 
# File 'lib/smplkit/jobs/models.rb', line 347

def id
  @id
end

#kind ⇒ String?

Returns Read-only. How the job runs, derived from its #schedule by the server: one of Smplkit::Jobs::JobKind::RECURRING, Smplkit::Jobs::JobKind::MANUAL, or Smplkit::Jobs::JobKind::ONE_OFF. nil on an unsaved instance.

Returns:



374
375
376
 
# File 'lib/smplkit/jobs/models.rb', line 374

def kind
  @kind
end

#name ⇒ String

Returns Human-readable name for the job.

Returns:

  • (String) —

    Human-readable name for the job.



350
351
352
 
# File 'lib/smplkit/jobs/models.rb', line 350

def name
  @name
end

#schedule ⇒ String?

Returns The base schedule every environment inherits, and the field that determines the job’s #kind: nil (omitted) for a permanent manual job that never auto-fires; a 5-field cron expression evaluated in UTC for a recurring job; an ISO-8601 datetime for a one-off run at that instant; or the literal “now” for a one-off run as soon as possible. A datetime or “now” job disables itself after it fires. The schedule is environment-agnostic — set it with #set_schedule.

Returns:

  • (String, nil) —

    The base schedule every environment inherits, and the field that determines the job’s #kind: nil (omitted) for a permanent manual job that never auto-fires; a 5-field cron expression evaluated in UTC for a recurring job; an ISO-8601 datetime for a one-off run at that instant; or the literal “now” for a one-off run as soon as possible. A datetime or “now” job disables itself after it fires. The schedule is environment-agnostic — set it with #set_schedule.



387
388
389
 
# File 'lib/smplkit/jobs/models.rb', line 387

def schedule
  @schedule
end

#type ⇒ String

Returns Job type. Only “http” is supported today.

Returns:

  • (String) —

    Job type. Only “http” is supported today.



377
378
379
 
# File 'lib/smplkit/jobs/models.rb', line 377

def type
  @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.



402
403
404
 
# File 'lib/smplkit/jobs/models.rb', line 402

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.



410
411
412
 
# File 'lib/smplkit/jobs/models.rb', line 410

def version
  @version
end

Class Method Details

.from_resource(resource, client: nil) ⇒ Job

Returns The hydrated job.

Parameters:

  • resource (Object) —

    The JSON:API resource (id + attributes).

  • client (JobsClient, nil) (defaults to: nil) —

    Client to bind the job to.

Returns:

  • (Job) —

    The hydrated job.



650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
 
# File 'lib/smplkit/jobs/models.rb', line 650

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] = JobEnvironment.from_wire(env_raw)
  end
  new(
    client,
    id: resource.id,
    name: a.name,
    description: a.description,
    # The base +enabled+ roll-up is derived from +environments+, not read
    # from the wire — the API no longer carries a top-level +enabled+.
    environments: environments,
    kind: a.kind,
    type: a.type || "http",
    schedule: a.schedule,
    configuration: HttpConfig.from_wire(a.configuration),
    concurrency_policy: a.concurrency_policy || "ALLOW",
    created_at: a.created_at,
    updated_at: a.updated_at,
    deleted_at: a.deleted_at,
    version: a.version
  )
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. 



628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
 
# File 'lib/smplkit/jobs/models.rb', line 628

def _apply(other)
  @id = other.id
  @name = other.name
  @description = other.description
  @environments = other.environments
  @kind = other.kind
  @type = other.type
  @schedule = other.schedule
  @configuration = other.configuration
  @concurrency_policy = other.concurrency_policy
  @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.



623
624
625
 
# File 'lib/smplkit/jobs/models.rb', line 623

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

#delete ⇒ nil Also known as: delete!

Delete this job on the server.

Returns:

  • (nil) 


461
462
463
464
465
 
# File 'lib/smplkit/jobs/models.rb', line 461

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

  @client.delete(@id)
end

#enabled ⇒ Boolean

Returns Derived roll-up: true when the job is enabled in at least one environment. Computed from #environments rather than read from the wire — the API no longer carries a top-level enabled. Set enablement per environment via #set_enabled / #environments.

Returns:

  • (Boolean) —

    Derived roll-up: true when the job is enabled in at least one environment. Computed from #environments rather than read from the wire — the API no longer carries a top-level enabled. Set enablement per environment via #set_enabled / #environments.



359
360
361
 
# File 'lib/smplkit/jobs/models.rb', line 359

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

#get_configuration(environment: nil) ⇒ HttpConfig

The job’s effective configuration.

With environment omitted (the default), returns the base configuration. With an environment, returns that environment’s configuration override when it has one, else the base configuration —the request the job actually sends when it fires in that environment.

Parameters:

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

    An environment key, or nil for the base configuration.

Returns:



549
550
551
552
553
554
555
 
# File 'lib/smplkit/jobs/models.rb', line 549

def get_configuration(environment: nil)
  unless environment.nil?
    override = @environments[environment]
    return override.configuration if override && !override.configuration.nil?
  end
  @configuration
end

#is_enabled(environment: nil) ⇒ Boolean

Whether the job is enabled.

With environment omitted (the default), returns the roll-up — true when the job is enabled in at least one environment. With an environment, returns whether the job is enabled in that specific environment.

Parameters:

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

    An environment key, or nil for the roll-up across every environment.

Returns:

  • (Boolean) 


490
491
492
493
494
495
496
497
 
# File 'lib/smplkit/jobs/models.rb', line 490

def is_enabled(environment: nil)
  return enabled if environment.nil?

  override = @environments[environment]
  return false if override.nil?

  override.enabled
end

#is_manual ⇒ Boolean

Whether this is a manual job — no schedule; runs only when triggered.

Returns:

  • (Boolean) 


509
510
511
 
# File 'lib/smplkit/jobs/models.rb', line 509

def is_manual
  @kind == JobKind::MANUAL
end

#is_one_off ⇒ Boolean

Whether this is a one-off job — a single now / datetime run.

Returns:

  • (Boolean) 


516
517
518
 
# File 'lib/smplkit/jobs/models.rb', line 516

def is_one_off
  @kind == JobKind::ONE_OFF
end

#is_recurring ⇒ Boolean

Whether this is a recurring (cron-scheduled) job.

Returns:

  • (Boolean) 


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

def is_recurring
  @kind == JobKind::RECURRING
end

#list_runs(environment: nil, page_size: nil, after: nil) ⇒ Array<Smplkit::Jobs::Run>

List this job’s run history, most recent first.

Parameters:

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

    Restrict to runs stamped with this environment. nil covers every environment you can access.

  • page_size (Integer, nil) (defaults to: nil) —

    Maximum number of runs to return in this page.

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

    Opaque cursor from a previous page.

Returns:

Raises:

  • (RuntimeError) —

    when this job has no bound client.



605
606
607
608
609
610
611
612
613
614
 
# File 'lib/smplkit/jobs/models.rb', line 605

def list_runs(environment: nil, page_size: nil, after: nil)
  raise "Job was constructed without a client; cannot list runs" if @client.nil?

  @client.runs.list(
    job: @id,
    environments: environment.nil? ? nil : [environment],
    page_size: page_size,
    after: after
  )
end

#save ⇒ self Also known as: save!

Create this job, or full-replace it if it already exists.

Upsert behavior is driven by #created_at: a job 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 created_at, version, and per-environment next_run_at inside #environments).

Returns:

  • (self) 


449
450
451
452
453
454
455
 
# File 'lib/smplkit/jobs/models.rb', line 449

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

  updated = @created_at.nil? ? @client._create_job(self) : @client._update_job(self)
  _apply(updated)
  self
end

#set_configuration(configuration, environment: nil) ⇒ Object

Set the job’s configuration — base (environment omitted) or per-environment.

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.

Parameters:

  • configuration (HttpConfig) —

    The HTTP request configuration.

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

    An environment key for a per-environment override, or nil to set the base configuration.



531
532
533
534
535
536
537
 
# File 'lib/smplkit/jobs/models.rb', line 531

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

#set_enabled(enabled, environment:) ⇒ Object

Enable or disable the job in a single environment.

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.

Parameters:

  • enabled (Boolean) —

    Whether the job should fire in this environment.

  • environment (String) —

    The environment key to enable / disable.



476
477
478
 
# File 'lib/smplkit/jobs/models.rb', line 476

def set_enabled(enabled, environment:)
  _environment_override(environment).enabled = enabled
end

#set_schedule(schedule, environment: nil) ⇒ Object

Set the job’s schedule — base (environment omitted) or per-environment.

With environment omitted (the default), sets the base #schedule —an ISO-8601 datetime, a 5-field UTC cron expression, or the literal “now” — which every environment inherits unless it overrides it.

With environment given, sets that environment’s per-environment cron schedule override on #environments, creating the override entry if it doesn’t exist yet (preserving any already-set enabled / configuration on it). A per-environment override is a cron expression only and varies the cadence within that environment; it cannot turn a one-off job recurring or vice-versa. Call #save to persist.

Parameters:

  • schedule (String) —

    An ISO-8601 datetime, a 5-field UTC cron expression, or the literal “now” (base); a 5-field UTC cron expression (per-environment).

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

    An environment key for a per-environment override, or nil to set the base schedule.



575
576
577
578
579
580
581
 
# File 'lib/smplkit/jobs/models.rb', line 575

def set_schedule(schedule, environment: nil)
  if environment.nil?
    @schedule = schedule
  else
    _environment_override(environment).schedule = schedule
  end
end

#trigger(environment: nil) ⇒ Smplkit::Jobs::Run

Trigger one immediate, manual run of this job (a MANUAL run).

Parameters:

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

    Environment the run executes in. Defaults to the client’s configured environment; when the job is enabled in exactly one environment that environment is used.

Returns:

Raises:

  • (RuntimeError) —

    when this job has no bound client.



590
591
592
593
594
 
# File 'lib/smplkit/jobs/models.rb', line 590

def trigger(environment: nil)
  raise "Job was constructed without a client; cannot trigger a run" if @client.nil?

  @client.run(@id, environment: environment)
end