Class: Smplkit::Jobs::Job

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

Overview

A scheduled unit of work: an HTTP request run on a schedule.

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

Enablement is per environment, set via #set_enabled (and read via #is_enabled); base #enabled is a read-only roll-up. The schedule is environment-agnostic — one cron / datetime / now shared across every environment the job runs in.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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

Returns a new instance of Job.



368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
 
# File 'lib/smplkit/jobs/models.rb', line 368

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

Instance Attribute Details

#birth_environment ⇒ Object 



366
367
368
 
# File 'lib/smplkit/jobs/models.rb', line 366

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.



342
343
344
 
# File 'lib/smplkit/jobs/models.rb', line 342

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.



338
339
340
 
# File 'lib/smplkit/jobs/models.rb', line 338

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.



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

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.



357
358
359
 
# File 'lib/smplkit/jobs/models.rb', line 357

def deleted_at
  @deleted_at
end

#description ⇒ String?

Returns Free-text description. nil when unset.

Returns:

  • (String, nil) —

    Free-text description. nil when unset.



305
306
307
 
# File 'lib/smplkit/jobs/models.rb', line 305

def description
  @description
end

#enabled ⇒ Boolean

Returns Read-only, server-derived roll-up: true when the job is enabled in at least one environment. Set enablement per environment via #set_enabled / #environments; mutating this field directly has no effect on the server (it is never written).

Returns:

  • (Boolean) —

    Read-only, server-derived roll-up: true when the job is enabled in at least one environment. Set enablement per environment via #set_enabled / #environments; mutating this field directly has no effect on the server (it is never written).



311
312
313
 
# File 'lib/smplkit/jobs/models.rb', line 311

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



319
320
321
 
# File 'lib/smplkit/jobs/models.rb', line 319

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.



299
300
301
 
# File 'lib/smplkit/jobs/models.rb', line 299

def id
  @id
end

#name ⇒ String

Returns Human-readable name for the job.

Returns:

  • (String) —

    Human-readable name for the job.



302
303
304
 
# File 'lib/smplkit/jobs/models.rb', line 302

def name
  @name
end

#next_run_at ⇒ String?

Returns The next scheduled fire time. nil once a one-off job has fired.

Returns:

  • (String, nil) —

    The next scheduled fire time. nil once a one-off job has fired.



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

def next_run_at
  @next_run_at
end

#recurring ⇒ Boolean?

Returns Read-only. true for a recurring (cron) schedule, false for a one-off datetime / now schedule. Derived from #schedule by the server.

Returns:

  • (Boolean, nil) —

    Read-only. true for a recurring (cron) schedule, false for a one-off datetime / now schedule. Derived from #schedule by the server.



324
325
326
 
# File 'lib/smplkit/jobs/models.rb', line 324

def recurring
  @recurring
end

#schedule ⇒ String

Returns When the job runs: an ISO-8601 datetime (a one-off run), a 5-field cron expression evaluated in UTC (recurring), or the literal “now” (run once, 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) —

    When the job runs: an ISO-8601 datetime (a one-off run), a 5-field cron expression evaluated in UTC (recurring), or the literal “now” (run once, as soon as possible). A datetime or “now” job disables itself after it fires. The schedule is environment-agnostic — set it with #set_schedule.



334
335
336
 
# File 'lib/smplkit/jobs/models.rb', line 334

def schedule
  @schedule
end

#type ⇒ String

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

Returns:

  • (String) —

    Job type. Only “http” is supported today.



327
328
329
 
# File 'lib/smplkit/jobs/models.rb', line 327

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.



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

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.



361
362
363
 
# File 'lib/smplkit/jobs/models.rb', line 361

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.



570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
 
# File 'lib/smplkit/jobs/models.rb', line 570

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+ is a server-derived roll-up; round-trip whatever
    # the server returned without assuming a default of true.
    enabled: a.enabled.nil? ? false : a.enabled,
    environments: environments,
    recurring: a.recurring,
    type: a.type || "http",
    schedule: a.schedule,
    configuration: HttpConfig.from_wire(a.configuration),
    concurrency_policy: a.concurrency_policy || "ALLOW",
    next_run_at: a.next_run_at,
    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. 



546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
 
# File 'lib/smplkit/jobs/models.rb', line 546

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



541
542
543
 
# File 'lib/smplkit/jobs/models.rb', line 541

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

#delete ⇒ nil Also known as: delete!

Delete this job on the server.

Returns:

  • (nil) 


413
414
415
416
417
 
# File 'lib/smplkit/jobs/models.rb', line 413

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

  @client.delete(@id)
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:



480
481
482
483
484
485
486
 
# File 'lib/smplkit/jobs/models.rb', line 480

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) 


442
443
444
445
446
447
448
449
 
# File 'lib/smplkit/jobs/models.rb', line 442

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

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

  override.enabled
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.



523
524
525
526
527
528
529
530
531
532
 
# File 'lib/smplkit/jobs/models.rb', line 523

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, next_run_at, and the derived enabled roll-up).

Returns:

  • (self) 


401
402
403
404
405
406
407
 
# File 'lib/smplkit/jobs/models.rb', line 401

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.



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

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.



428
429
430
 
# File 'lib/smplkit/jobs/models.rb', line 428

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

#set_schedule(schedule) ⇒ Object

Set the job’s schedule.

The schedule is environment-agnostic — a job has a single cron / datetime / “now” schedule shared across every environment it runs in (each enabled environment fires on the same cadence). There is no per-environment schedule, so this setter takes no environment.

Parameters:

  • schedule (String) —

    An ISO-8601 datetime, a 5-field UTC cron expression, or the literal “now”.



497
498
499
 
# File 'lib/smplkit/jobs/models.rb', line 497

def set_schedule(schedule)
  @schedule = schedule
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.



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

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

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