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. When omitted, resolved from SMPLKIT_ENVIRONMENT or ~/.smplkit. 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.



341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
 
# File 'lib/smplkit/jobs/client.rb', line 341

def initialize(api_key = nil, profile: nil, base_domain: nil, scheme: nil,
               debug: nil, extra_headers: nil, environment: nil, auth_client: nil)
  if auth_client.nil?
    # Standalone: resolve like Smplkit::Client — defaults → ~/.smplkit →
    # SMPLKIT_* env vars → constructor args — environment included.
    auth, resolved_env = Jobs.jobs_transport(
      api_key: api_key, profile: profile, base_domain: base_domain,
      scheme: scheme, environment: environment, debug: debug, extra_headers: extra_headers
    )
    @environment = resolved_env
  else
    auth = auth_client
    @environment = environment
  end
  @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:



322
323
324
 
# File 'lib/smplkit/jobs/client.rb', line 322

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



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

def runs
  @runs
end

Class Method Details

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

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



368
369
370
371
372
373
374
375
 
# File 'lib/smplkit/jobs/client.rb', line 368

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) 


564
565
566
567
568
569
 
# File 'lib/smplkit/jobs/client.rb', line 564

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


579
580
581
582
583
584
 
# File 'lib/smplkit/jobs/client.rb', line 579

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



363
364
365
 
# File 'lib/smplkit/jobs/client.rb', line 363

def close
  nil
end

#delete(id) ⇒ nil

Delete a job by its id.

Parameters:

  • id (String) —

    Identifier of the job to delete.

Returns:

  • (nil) 


521
522
523
524
 
# File 'lib/smplkit/jobs/client.rb', line 521

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:



512
513
514
515
 
# File 'lib/smplkit/jobs/client.rb', line 512

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:



495
496
497
498
499
500
501
502
503
504
505
 
# File 'lib/smplkit/jobs/client.rb', line 495

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:



440
441
442
443
444
445
446
447
 
# File 'lib/smplkit/jobs/client.rb', line 440

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



406
407
408
409
410
411
412
413
 
# File 'lib/smplkit/jobs/client.rb', line 406

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



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

def run(id, environment: nil)
  env = environment.nil? ? @environment : environment
  # The target environment now travels in the run-now request body (the
  # X-Smplkit-Environment header was dropped). When no environment is
  # resolved, send no body at all so the service implies it.
  opts = {}
  opts[:run_now_request] = SmplkitGeneratedClient::Jobs::RunNowRequest.new(environment: env) unless env.nil?
  resp = Jobs.call_api { @api.run_job_now(id, opts) }
  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:



470
471
472
473
474
475
476
477
478
 
# File 'lib/smplkit/jobs/client.rb', line 470

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: birth_env_map(environment.nil? ? @environment : environment),
        concurrency_policy: concurrency_policy
  )
end

#usage ⇒ Smplkit::Jobs::Usage

Current-period usage counters for the account.

Returns:



554
555
556
557
 
# File 'lib/smplkit/jobs/client.rb', line 554

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