Class: Smplkit::Jobs::JobsClient

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

Overview

The active-record entry points are #new_recurring_job, #new_manual_job, and #schedule: instantiate a draft, mutate fields, then call Smplkit::Jobs::Job#save. Run history and the cancel / rerun run actions live on #runs.

Reachable as client.jobs (Smplkit::Client) or constructed directly —JobsClient.new resolves credentials from ~/.smplkit / env vars.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key = nil, profile: nil, base_domain: nil, scheme: nil, debug: nil, extra_headers: nil, environment: nil, auth_client: nil) ⇒ JobsClient

Returns a new instance of JobsClient.

Parameters:

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

    API key. When omitted, resolved from SMPLKIT_API_KEY or ~/.smplkit.

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

    Named ~/.smplkit profile section.

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

    Base domain for API requests (default “smplkit.com”).

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

    URL scheme (default “https”).

  • debug (Boolean, nil) (defaults to: nil) —

    Enable SDK debug logging.

  • extra_headers (Hash, nil) (defaults to: nil) —

    Extra headers attached to every request.

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

    Default environment for environment-scoped operations — the environment a one-off job created through this client is born in, the default a manual run executes in, and the default scope for runs.list. nil leaves these unset (the credential’s permitted environment is implied where unambiguous).

  • auth_client (Object, nil) (defaults to: nil) —

    Internal — a pre-built transport supplied by a top-level client so the jobs surface shares one connection pool. Not for direct use.



335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/smplkit/jobs/client.rb', line 335

def initialize(api_key = nil, profile: nil, base_domain: nil, scheme: nil,
               debug: nil, extra_headers: nil, environment: nil, auth_client: nil)
  auth = auth_client || Jobs.jobs_transport(
    api_key: api_key, profile: profile, base_domain: base_domain,
    scheme: scheme, debug: debug, extra_headers: extra_headers
  )
  @environment = environment
  @api = SmplkitGeneratedClient::Jobs::JobsApi.new(auth)
  @runs = RunsClient.new(SmplkitGeneratedClient::Jobs::RunsApi.new(auth), environment: environment)
  @retry_policies = RetryPoliciesClient.new(SmplkitGeneratedClient::Jobs::RetryPoliciesApi.new(auth))
  @usage_api = SmplkitGeneratedClient::Jobs::UsageApi.new(auth)
end

Instance Attribute Details

#retry_policies ⇒ RetryPoliciesClient (readonly)

Returns Reusable retry policies (client.jobs.retry_policies).

Returns:



317
318
319
 
# File 'lib/smplkit/jobs/client.rb', line 317

def retry_policies
  @retry_policies
end

#runs ⇒ RunsClient (readonly)

Returns Run history and run actions (client.jobs.runs).

Returns:

  • (RunsClient) —

    Run history and run actions (client.jobs.runs).



313
314
315
 
# File 'lib/smplkit/jobs/client.rb', line 313

def runs
  @runs
end

Class Method Details

.open(*args, **kwargs) ⇒ Object

Construct, yield to the block, and close on exit.



355
356
357
358
359
360
361
362
 
# File 'lib/smplkit/jobs/client.rb', line 355

def self.open(*args, **kwargs)
  client = new(*args, **kwargs)
  begin
    yield client
  ensure
    client.close
  end
end

Instance Method Details

#_create_job(job) ⇒ Object

Raises:

  • (ArgumentError) 


544
545
546
547
548
549
 
# File 'lib/smplkit/jobs/client.rb', line 544

def _create_job(job)
  raise ArgumentError, "Job.id is required on create (caller-supplied key)" if job.id.nil? || job.id.empty?

  resp = Jobs.call_api { @api.create_job(build_create_body(job), x_smplkit_environment: job.birth_environment) }
  Job.from_resource(resp.data, client: self)
end

#_update_job(job) ⇒ Object

Header values come back in plaintext on the GET path, so a fetched job round-trips through this full-replace PUT with its header values intact — no need to re-enter secrets.

Raises:

  • (ArgumentError) 


559
560
561
562
563
564
 
# File 'lib/smplkit/jobs/client.rb', line 559

def _update_job(job)
  raise ArgumentError, "cannot update a Job with no id" if job.id.nil?

  resp = Jobs.call_api { @api.update_job(job.id, build_body(job), x_smplkit_environment: @environment) }
  Job.from_resource(resp.data, client: self)
end

#close ⇒ Object

The generated ApiClient owns Faraday connections that release on GC; there is no explicit shutdown to call.



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

def close
  nil
end

#delete(id) ⇒ nil

Delete a job by its id.

Parameters:

  • id (String) —

    Identifier of the job to delete.

Returns:

  • (nil) 


507
508
509
510
 
# File 'lib/smplkit/jobs/client.rb', line 507

def delete(id)
  Jobs.call_api { @api.delete_job(id) }
  nil
end

#get(id) ⇒ Smplkit::Jobs::Job

Fetch a single job by id. The returned instance is bound to this client, so job.save and job.delete work.

Parameters:

  • id (String)

Returns:



498
499
500
501
 
# File 'lib/smplkit/jobs/client.rb', line 498

def get(id)
  resp = Jobs.call_api { @api.get_job(id) }
  Job.from_resource(resp.data, client: self)
end

#list(kind: nil, scheduled: nil, name: nil, page_number: nil, page_size: nil) ⇒ Array<Smplkit::Jobs::Job>

List jobs for the authenticated account.

Parameters:

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

    Filter to a single Smplkit::Jobs::JobKind (JobKind::RECURRING / JobKind::MANUAL / JobKind::ONE_OFF). nil lists recurring and manual jobs; one-off jobs are omitted unless you pass JobKind::ONE_OFF.

  • scheduled (Boolean, nil) (defaults to: nil) —

    Filter to jobs that have an upcoming fire in some environment (true) or none (false) — the feed for an upcoming-runs view, which includes one-offs. nil does not filter on scheduling.

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

    Filter to jobs whose name contains this text (case-insensitive). nil lists all.

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

    1-based page number to return.

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

    Items per page.

Returns:



481
482
483
484
485
486
487
488
489
490
491
 
# File 'lib/smplkit/jobs/client.rb', line 481

def list(kind: nil, scheduled: nil, name: nil, page_number: nil, page_size: nil)
  opts = {}
  opts[:filter_kind] = kind unless kind.nil?
  opts[:filter_scheduled] = scheduled unless scheduled.nil?
  opts[:filter_name] = name unless name.nil?
  opts[:page_number] = page_number unless page_number.nil?
  opts[:page_size] = page_size unless page_size.nil?

  resp = Jobs.call_api { @api.list_jobs(opts) }
  (resp.data || []).map { |r| Job.from_resource(r, client: self) }
end

#new_manual_job(id, name:, configuration:, description: nil, environments: nil, concurrency_policy: "ALLOW", retry_policy: nil) ⇒ Smplkit::Jobs::Job

Construct an unsaved manual Smplkit::Jobs::Job bound to this client. Call #save on the returned instance to create it.

A manual job has no schedule — it never auto-fires and runs only when triggered via #run / Smplkit::Jobs::Job#trigger.

Parameters:

  • id (String) —

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

  • name (String) —

    Human-readable name for the job.

  • configuration (Smplkit::Jobs::HttpConfig) —

    The HTTP request the job sends each time it runs.

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

    Optional free-text description.

  • environments (Hash{String => Smplkit::Jobs::JobEnvironment, Hash}, nil) (defaults to: nil) —

    Per-environment sparse overrides keyed by environment key — each a Smplkit::Jobs::JobEnvironment, or a plain hash of its constructor kwargs (+{ enabled: true }+, optionally with request leaves like :url and a :headers name→value map). Each entry overrides only the leaves it sets; the job is triggerable only in environments enabled here.

  • concurrency_policy (String) (defaults to: "ALLOW") —

    How overlapping runs are handled. Defaults to “ALLOW”.

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

    Retry policy for failed runs — the id of a RetryPolicy, overridable per environment. nil (the default) uses the built-in “Default” policy, which never retries.

Returns:



427
428
429
430
431
432
433
434
 
# File 'lib/smplkit/jobs/client.rb', line 427

def new_manual_job(id, name:, configuration:, description: nil,
                   environments: nil, concurrency_policy: "ALLOW", retry_policy: nil)
  _new_job(
    id, name: name, schedule: nil, retry_policy: retry_policy,
        configuration: configuration, description: description, environments: environments,
        concurrency_policy: concurrency_policy, environment: nil
  )
end

#new_recurring_job(id, name:, schedule:, configuration:, timezone: nil, retry_policy: nil, description: nil, environments: nil, concurrency_policy: "ALLOW") ⇒ Smplkit::Jobs::Job

Construct an unsaved recurring Smplkit::Jobs::Job bound to this client. Call #save on the returned instance to create it.

Parameters:

  • id (String) —

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

  • name (String) —

    Human-readable name for the job.

  • schedule (String) —

    The base cadence — a 5-field cron expression evaluated in the job’s timezone (UTC by default), e.g. “0 2 * * *” —that every environment inherits unless it sets its own override.

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

    Base IANA timezone the cron schedule is evaluated in (e.g. “America/New_York”), DST-aware. nil (the default) means UTC. Every environment inherits it unless it overrides it.

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

    Base retry policy for failed runs — the id of a RetryPolicy, overridable per environment. nil (the default) uses the built-in “Default” policy, which never retries.

  • configuration (Smplkit::Jobs::HttpConfig) —

    The HTTP request the job sends each time it fires.

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

    Optional free-text description.

  • environments (Hash{String => Smplkit::Jobs::JobEnvironment, Hash}, nil) (defaults to: nil) —

    Per-environment sparse overrides keyed by environment key — each a Smplkit::Jobs::JobEnvironment, or a plain hash of its constructor kwargs (+{ enabled: true }+, optionally with :schedule, :timezone, :retry_policy, request leaves like :url, and a :headers name→value map). Each entry overrides only the leaves it sets; the job is scheduled only in environments enabled here.

  • concurrency_policy (String) (defaults to: "ALLOW") —

    How overlapping runs are handled. Defaults to “ALLOW”.

Returns:



393
394
395
396
397
398
399
400
 
# File 'lib/smplkit/jobs/client.rb', line 393

def new_recurring_job(id, name:, schedule:, configuration:, timezone: nil, retry_policy: nil,
                      description: nil, environments: nil, concurrency_policy: "ALLOW")
  _new_job(
    id, name: name, schedule: schedule, timezone: timezone, retry_policy: retry_policy,
        configuration: configuration, description: description, environments: environments,
        concurrency_policy: concurrency_policy, environment: nil
  )
end

#run(id, environment: nil) ⇒ Smplkit::Jobs::Run

Trigger one immediate, manual run of a job, ignoring its schedule.

This starts an ad-hoc run right now in addition to any scheduled runs; it does not alter the job’s schedule. To read or act on existing runs, use client.jobs.runs.

Parameters:

  • id (String) —

    Identifier of the job to run.

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

    Environment the manual run executes in. Defaults to the client’s configured environment; when the job is enabled in exactly one environment that environment is used, and a single-environment credential implies it. The job must be enabled in the chosen environment.

Returns:



526
527
528
529
530
 
# File 'lib/smplkit/jobs/client.rb', line 526

def run(id, environment: nil)
  env = environment.nil? ? @environment : environment
  resp = Jobs.call_api { @api.run_job_now(id, x_smplkit_environment: env) }
  Run.from_resource(resp.data, runs: @runs)
end

#schedule(id, name:, schedule:, configuration:, description: nil, concurrency_policy: "ALLOW", retry_policy: nil, environment: nil) ⇒ Smplkit::Jobs::Job

Construct an unsaved one-off Smplkit::Jobs::Job bound to this client. Call #save on the returned instance to create it.

A one-off job runs a single time at schedule and is then spent.

Parameters:

  • id (String) —

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

  • name (String) —

    Human-readable name for the job.

  • schedule (Time) —

    The instant the single run fires.

  • configuration (Smplkit::Jobs::HttpConfig) —

    The HTTP request the job sends when it runs.

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

    Optional free-text description.

  • concurrency_policy (String) (defaults to: "ALLOW") —

    How overlapping runs are handled. Defaults to “ALLOW”.

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

    Retry policy for failed runs — the id of a RetryPolicy. nil (the default) uses the built-in “Default” policy, which never retries.

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

    The environment the job is born in. Defaults to the client’s configured environment.

Returns:



457
458
459
460
461
462
463
464
 
# File 'lib/smplkit/jobs/client.rb', line 457

def schedule(id, name:, schedule:, configuration:, description: nil,
             concurrency_policy: "ALLOW", retry_policy: nil, environment: nil)
  _new_job(
    id, name: name, schedule: schedule.iso8601, retry_policy: retry_policy,
        configuration: configuration, description: description, environments: nil,
        concurrency_policy: concurrency_policy, environment: environment
  )
end

#usage ⇒ Smplkit::Jobs::Usage

Current-period usage counters for the account.

Returns:



535
536
537
538
 
# File 'lib/smplkit/jobs/client.rb', line 535

def usage
  resp = Jobs.call_api { @usage_api.get_usage }
  Usage.from_resource(resp.data)
end