add documentation

This commit is contained in:
Andrew Cantino 2014-01-09 14:26:46 -08:00
parent 3bf1961ef6
commit d7d2bfe7d2
9 changed files with 39 additions and 6 deletions

View file

@ -3,6 +3,9 @@ require 'assignable_types'
require 'markdown_class_attributes'
require 'utils'
# Agent is the core class in Huginn, representing a configurable, schedulable, reactive system with memory that can
# be sub-classed for many different purposes. Agents can emit Events, as well as receive them and react in many different ways.
# The basic Agent API is detailed on the Huginn wiki: https://github.com/cantino/huginn/wiki/Creating-a-new-agent
class Agent < ActiveRecord::Base
include AssignableTypes
include MarkdownClassAttributes
@ -226,6 +229,9 @@ class Agent < ActiveRecord::Base
!!@cannot_receive_events
end
# Find all Agents that have received Events since the last execution of this method. Update those Agents with
# their new `last_checked_event_id` and queue each of the Agents to be called with #receive using `async_receive`.
# This is called by bin/schedule.rb periodically.
def receive!
Agent.transaction do
sql = Agent.
@ -256,9 +262,9 @@ class Agent < ActiveRecord::Base
end
# Given an Agent id and an array of Event ids, load the Agent, call #receive on it with the Event objects, and then
# save it with an updated _last_receive_at_ timestamp.
# save it with an updated `last_receive_at` timestamp.
#
# This method is tagged with _handle_asynchronously_ and will be delayed and run with delayed_job. It accepts Agent
# This method is tagged with `handle_asynchronously` and will be delayed and run with delayed_job. It accepts Agent
# and Event ids instead of a literal ActiveRecord models because it is preferable to serialize delayed_jobs with ids.
def async_receive(agent_id, event_ids)
agent = Agent.find(agent_id)
@ -273,6 +279,8 @@ class Agent < ActiveRecord::Base
end
handle_asynchronously :async_receive
# Given a schedule name, run `check` via `bulk_check` on all Agents with that schedule.
# This is called by bin/schedule.rb for each schedule in `SCHEDULES`.
def run_schedule(schedule)
types = where(:schedule => schedule).group(:type).pluck(:type)
types.each do |type|
@ -280,7 +288,8 @@ class Agent < ActiveRecord::Base
end
end
# You can override this to define a custom bulk_check for your type of Agent.
# Schedule `async_check`s for every Agent on the given schedule. This is normally called by `run_schedule` once
# per type of agent, so you can override this to define custom bulk check behavior for your custom Agent type.
def bulk_check(schedule)
raise "Call #bulk_check on the appropriate subclass of Agent" if self == Agent
where(:schedule => schedule).pluck("agents.id").each do |agent_id|
@ -288,10 +297,11 @@ class Agent < ActiveRecord::Base
end
end
# Given an Agent id, load the Agent, call #check on it, and then save it with an updated _last_check_at_ timestamp.
# Given an Agent id, load the Agent, call #check on it, and then save it with an updated `last_check_at` timestamp.
#
# This method is tagged with _handle_asynchronously_ and will be delayed and run with delayed_job. It accepts an Agent
# id instead of a literal Agent because it is preferable to serialize delayed_jobs with ids.
# This method is tagged with `handle_asynchronously` and will be delayed and run with delayed_job. It accepts an Agent
# id instead of a literal Agent because it is preferable to serialize delayed_jobs with ids, instead of with the full
# Agents.
def async_check(agent_id)
agent = Agent.find(agent_id)
begin

View file

@ -1,3 +1,6 @@
# AgentLogs are temporary records of Agent activity, intended for debugging and error tracking. They can be viewed
# in Agents' detail pages. AgentLogs with a `level` of 4 or greater are considered "errors" and automatically update
# Agents' `last_error_log_at` column. These are often used to determine if an Agent is `working?`.
class AgentLog < ActiveRecord::Base
attr_accessible :agent, :inbound_event, :level, :message, :outbound_event

View file

@ -1,3 +1,5 @@
# Contacts are used only for the contact form on the Huginn website. If you host a public Huginn instance, you can use
# these to receive messages from visitors.
class Contact < ActiveRecord::Base
attr_accessible :email, :message, :name

View file

@ -1,5 +1,8 @@
require 'json_serialized_field'
# Events are how Huginn Agents communicate and log information about the world. Events can be emitted and received by
# Agents. They contain a serialized `payload` of arbitrary JSON data, as well as optional `lat`, `lng`, and `expires_at`
# fields.
class Event < ActiveRecord::Base
include JSONSerializedField
@ -16,10 +19,13 @@ class Event < ActiveRecord::Base
where("events.created_at > ?", timespan)
}
# Emit this event again, as a new Event.
def reemit!
agent.create_event :payload => payload, :lat => lat, :lng => lng
end
# Look for Events whose `expires_at` is present and in the past. Remove those events and then update affected Agents'
# `events_counts` cache columns. This method is called by bin/schedule.rb periodically.
def self.cleanup_expired!
affected_agents = Event.where("expires_at IS NOT NULL AND expires_at < ?", Time.now).group("agent_id").pluck(:agent_id)
Event.where("expires_at IS NOT NULL AND expires_at < ?", Time.now).delete_all

View file

@ -1,3 +1,4 @@
# A Link connects Agents in a directed Event flow from the `source` to the `receiver`.
class Link < ActiveRecord::Base
attr_accessible :source_id, :receiver_id

View file

@ -1,3 +1,4 @@
# Huginn is designed to be a multi-User system. Users have many Agents (and Events created by those Agents).
class User < ActiveRecord::Base
# Include default devise modules. Others available are:
# :token_authenticatable, :confirmable,

View file

@ -1,5 +1,8 @@
#!/usr/bin/env ruby
# If you're using the backup gem, described on the Huginn wiki and at doc/deployment/backup, then you can use this
# utility to decrypt backups.
in_file = ARGV.shift
out_file = ARGV.shift || "decrypted_backup.tar"

View file

@ -1,5 +1,8 @@
#!/usr/bin/env ruby
# This process is used to maintain Huginn's upkeep behavior, automatically running scheduled Agents and
# periodically propagating and expiring Events. It's typically run via foreman and the included Procfile.
unless defined?(Rails)
puts
puts "Please run me with rails runner, for example:"

View file

@ -1,5 +1,9 @@
#!/usr/bin/env ruby
# This process is used by TwitterStreamAgents to watch the Twitter stream in real time. It periodically checks for
# new or changed TwitterStreamAgents and starts to follow the stream for them. It is typically run by foreman via
# the included Procfile.
unless defined?(Rails)
puts
puts "Please run me with rails runner, for example:"