Module: Locd::Agent::System::ClassMethods

Defined in:
lib/locd/agent/system.rb

Overview

Mixed in to classes themselves that include Locd::Agent::System.

Querying collapse

Creating the Agent collapse

Instance Method Summary collapse

Instance Method Details

#add(**kwds) ⇒ Locd::Agent

Wrapper that passes keywords though #default_write_kwds before calling the super method.

Parameters:

  • label: (String) —

    The agent's label, which is its:

    1. Unique identifier in launchd
    2. Domain via the proxy.
    3. Property list filename (plus the .plist extension).
  • force: (Boolean) —

    Overwrite any existing agent with the same label.

  • workdir: (String | Pathname) —

    Working directory for the agent.

  • **kwds (Hash<Symbol, Object>) —

    Additional keyword arguments to pass to #create_plist_data.

Returns:



297
298
299
 
# File 'lib/locd/agent/system.rb', line 297

def add **kwds
  super **default_write_kwds( **kwds )
end

#create_plist_data(**kwds) ⇒ Hash<String, Object>

Wrapper that passes keywords though #default_write_kwds before calling the super method.

Parameters:

  • log_path: (nil | String | Pathname) —

    Optional path to log agent standard outputs to (combined STDOUT and STDERR).

    See resolve_log_path for details on how the different types and values are treated.

Returns:

  • (Hash<String, Object>) — 



285
286
287
 
# File 'lib/locd/agent/system.rb', line 285

def create_plist_data **kwds
  super **default_write_kwds( **kwds )
end

#default_log_path(workdir, label) ⇒ Pathname

By default system agent logs are placed in the Loc'd log directory, which is <locd_home>/log and named <label>.log.

It does not depend on the workdir parameter at all - workdir is only included to conform to the Locd::Agent.default_log_path signature.

Examples:

# Considering
Locd.config.log_dir
# => #<Pathname:/Users/nrser/.locd/log>

# then
default_log_path _, 'com.nrser.locd.proxy'
# => #<Pathname:/Users/nrser/.locd/log/com.nrser.locd.proxy.log>

Parameters:

  • workdir (Pathname) —

    Not used.

  • label (String) —

    The agent's label.

Returns:

  • (Pathname) —

    Absolute path to the log file.

See Also:



178
179
180
 
# File 'lib/locd/agent/system.rb', line 178

def default_log_path workdir, label
  Locd.config.log_dir / "#{ label }.log"
end

#default_write_kwds(bin: Locd.config[:bin], workdir: Locd.config.home_dir, **kwds) ⇒ Object

Wrapper that keyword arguments to .add and .create_plist_data are passed through before forwarding up to the super method.

Provides default values and checks that necessary values like label and is_system are either not provided in the call or match the expected values.

Parameters:

  • bin: (String) (defaults to: Locd.config[:bin]) —

    The executable that will be used by system agents to call Loc'd.

  • **kwds —

    Merged into the returned Hash.

  • workdir: (String | Pathname) (defaults to: Locd.config.home_dir) —

    Working directory for the agent.

Raises:

  • (ArgumentError) —

    If kwds contains bad values.



232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/locd/agent/system.rb', line 232

def default_write_kwds  bin: Locd.config[:bin],
                        workdir: Locd.config.home_dir,
                        **kwds
  
  if kwds.key?( :is_system ) && kwds[:is_system] != true
    raise ArgumentError.new binding.erb <<~END
      The `:is_system` keyword **must** be `true` for system agents.
      
      It's how we recognize them!
      
      Found
      
          <%= kwds[:is_system] %>
      
    END
  end
  
  if kwds.key?( :label ) && kwds[:label] != self.label
    raise ArgumentError.new binding.erb <<~END
      Can not customize system agent labels!
      
      It **must** be `<%= self.label %>`, because that's how Loc'd finds it.
      
      You can change the part before the `.proxy` via the
      
          locd.namespace.label
      
      configuration value. Create or edit the file at
      
          <%= Locd.config.user_config_path %>
      
      to define overrides (nested YAML hashes, deep merged).
      
    END
  end
  
  {
    bin: bin.to_s,
    workdir: workdir,
    **kwds,
    is_system: true,
    label: self.label,
  }
end

#get(label = self.label) ⇒ Locd::Agent?

Get the agent.

Returns:

  • (Locd::Agent) —

    If the agent exists.

  • (nil) —

    If the agent does not exist.



194
195
196
197
198
199
200
201
 
# File 'lib/locd/agent/system.rb', line 194

def get label = self.label
  unless label == self.label
    raise NRSER::AttributeError.new \
      "System agents have a fixed label, must be", self.label
  end
  
  super( label )
end

#get!(label = self.label) ⇒ Object 



204
205
206
 
# File 'lib/locd/agent/system.rb', line 204

def get! label = self.label
  super( label )
end

#label ⇒ Object 



124
125
126
 
# File 'lib/locd/agent/system.rb', line 124

def label
  "#{ Locd.config[:namespace, :label] }.#{ label_name }"
end

#plist?(plist) ⇒ Boolean

The property lists for system agents are identified by their unique label (unique to the label namespace).

Parameters:

  • plist (Hash<String, Object>) —

Returns:

  • (Boolean) —

    true if the plist looks like it's from Loc'd.



135
136
137
 
# File 'lib/locd/agent/system.rb', line 135

def plist? plist
  plist['Label'] == self.label
end

#plist_abs_path(label = self.label) ⇒ Pathname

Overridden as convenience, defaults the label to .label.

Parameters:

  • label (String) (defaults to: self.label) —

    The agent's label.

Returns:

  • (Pathname) 


145
146
147
 
# File 'lib/locd/agent/system.rb', line 145

def plist_abs_path label = self.label
  super label
end