Module: Smplkit::Jobs

Defined in:
lib/smplkit/jobs/models.rb,
lib/smplkit/jobs/client.rb

Overview

Smpl Jobs surface — exposed through client.jobs.*.

Unlike Config/Flags/Logging, Jobs has no live “phone-home” agent — no environment registration, no WebSocket — so its entire surface lives on a single client. A Job is an active record: build it with client.jobs.new(…), set fields, and call Job#save (create when new, full-replace update when it already exists) or Job#delete. Runs are read-only views with rerun / cancel actions; run history lives on client.jobs.runs.

A job is enabled per environment: a recurring (cron) job may run in several environments at once, a one-off (now / future datetime) job runs a single time in the environment it was created in. Base enabled is a read-only, server-derived roll-up (true when enabled in at least one environment).

Defined Under Namespace

Modules: HttpMethod Classes: HttpConfig, HttpHeader, Job, JobEnvironment, JobsClient, Run, RunsClient, Usage

Class Method Summary collapse

Class Method Details

.call_api ⇒ Object

Wrap a generated-jobs-API call and translate ApiError into the Smplkit::Error hierarchy. Connection-level failures (no response code) become ConnectionError; status-coded failures route through Errors.raise_for_status, which emits PaymentRequiredError / NotFoundError / ConflictError / ValidationError / Error depending on the JSON:API body.



25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/smplkit/jobs/models.rb', line 25

def self.call_api
  yield
rescue SmplkitGeneratedClient::Jobs::ApiError => e
  raise Smplkit::ConnectionError, e.message.to_s if e.code.nil? || e.code.zero?

  Smplkit::Errors.raise_for_status(e.code, e.response_body.to_s)
  # raise_for_status only returns on 2xx; if we get here the generated
  # layer raised on a 2xx (shouldn't happen) — re-raise the original so
  # the caller can inspect.
  raise
end

.jobs_transport(api_key:, profile:, base_domain:, scheme:, debug:, extra_headers:) ⇒ Object

The Smpl Jobs client — accessed via client.jobs.

Unlike Config/Flags/Logging, Jobs has no live “phone-home” agent — no environment registration, no WebSocket — so its entire surface lives on one client. Defining a job, triggering a run, and reading run history are all plain request/response calls here:

client.jobs.{new,get,list,delete,run,usage}
client.jobs.runs.{list,get,cancel,rerun}
Job#{save,delete,trigger,list_runs}
Run#{rerun,cancel}

Build a standalone Smpl Jobs transport from resolved config.

Reuses the config resolver (jobs is account-global and never environment-scoped at the transport layer) so a standalone jobs client resolves credentials/base-domain from ~/.smplkit / env vars / constructor args exactly like the top-level clients do. Smpl Jobs is JSON:API, so the transport carries the application/vnd.apijson+ Accept header.



114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/smplkit/jobs/client.rb', line 114

def self.jobs_transport(api_key:, profile:, base_domain:, scheme:, debug:, extra_headers:)
  cfg = ConfigResolution.resolve_client_config(
    profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme, debug: debug
  )
  merged = {}
  merged.merge!(cfg.extra_headers || {})
  merged.merge!(extra_headers || {})
  tcfg = ConfigResolution::ResolvedClientConfig.new(
    api_key: cfg.api_key, base_domain: cfg.base_domain, scheme: cfg.scheme,
    debug: cfg.debug, extra_headers: merged
  )
  Transport.build_api_client(SmplkitGeneratedClient::Jobs, "jobs", tcfg, accept: "application/vnd.api+json")
end

.join_environments(environments) ⇒ 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.

Coerce a caller-supplied environments value into the comma-separated string the GET /api/v1/runs endpoint expects for filter[environment], or nil when no filter should be sent.

nil or an empty array (or one whose entries are all blank) returns nil so the caller omits the query param entirely and the read covers every environment the credential can access.



46
47
48
49
50
51
 
# File 'lib/smplkit/jobs/models.rb', line 46

def self.join_environments(environments)
  return nil if environments.nil?

  values = Array(environments).map { |e| e.to_s.strip }.reject(&:empty?)
  values.empty? ? nil : values.join(",")
end

.normalize_environments(environments) ⇒ 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.

Coerce a caller’s environments map to JobEnvironment instances.

Accepts either JobEnvironment values or plain hashes (+{ enabled: true, configuration: HttpConfig.new(…) }+) so callers can use the lightweight hash form without importing the model. A dict-form configuration override is coerced to an HttpConfig so it serializes on save.



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/smplkit/jobs/models.rb', line 82

def self.normalize_environments(environments)
  return {} if environments.nil? || environments.empty?

  environments.each_with_object({}) do |(env_key, value), out|
    out[env_key.to_s] = if value.is_a?(JobEnvironment)
                          value
                        else
                          cfg = value[:configuration] || value["configuration"]
                          cfg = HttpConfig.new(**cfg) if cfg.is_a?(Hash)
                          JobEnvironment.new(
                            enabled: value[:enabled] || value["enabled"] || false,
                            configuration: cfg
                          )
                        end
  end
end

.resolve_environment_filter(environments, default) ⇒ String?

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.

Resolve the filter[environment] value for the runs listing.

An explicit, non-empty environments list always wins and is comma-joined via join_environments. Otherwise the client’s configured default environment scopes the read. A client with no configured environment and no explicit list returns nil so the caller omits the query param and the credential’s own scoping applies server-side.

Parameters:

  • environments (Array<String>, String, nil) —

    Explicit per-call environment filter; an empty/blank value falls through to default.

  • default (String, nil) —

    The client’s configured environment.

Returns:

  • (String, nil) —

    The filter[environment] value, or nil to omit it.



66
67
68
69
70
71
 
# File 'lib/smplkit/jobs/models.rb', line 66

def self.resolve_environment_filter(environments, default)
  joined = join_environments(environments)
  return joined unless joined.nil?

  default
end