Page MenuHomeClusterLabs Projects
Diviner Tech Docs DoorkeeperFeedWorker

abstract class DoorkeeperFeedWorker
Phorge Technical Documentation (Doorkeeper)

Publish events (like comments on a revision) to external objects which are linked through Doorkeeper (like a linked JIRA or Asana task).

These workers are invoked by feed infrastructure during normal task queue operations. They read feed stories and publish information about them to external systems, generally mirroring comments and updates in Phabricator into remote systems by making API calls.

Tasks

Configuring Retries and Failures

  • public function getRequiredLeaseTime() — Return the number of seconds this worker needs hold a lease on the task for while it performs work. For most tasks you can leave this at `null`, which will give you a default lease (currently 2 hours).
  • public function getMaximumRetryCount() — By default, Doorkeeper workers perform a small number of retries with exponential backoff. A consideration in this policy is that many of these workers are laden with side effects.
  • public function getWaitBeforeRetry($task) — See @{method:getMaximumRetryCount} for a description of Doorkeeper retry defaults.

Publishing Stories

  • abstract protected function publishFeedStory() — Actually publish the feed story. Subclasses will generally make API calls to publish some version of the story into external systems.
  • abstract public function isEnabled() — Enable or disable the worker. Normally, this checks configuration to see if Phabricator is linked to applicable external systems.

Story Context

  • protected function getFeedStory() — Get the @{class:PhabricatorFeedStory} that should be published.
  • protected function getViewer() — Get the viewer for the act of publishing.
  • protected function getPublisher() — Get the @{class:DoorkeeperFeedStoryPublisher} which handles this object.
  • protected function getStoryObject() — Get the primary object the story is about, like a @{class:DifferentialRevision} or @{class:ManiphestTask}.

Internals

  • private function loadPublisher() — Load the @{class:DoorkeeperFeedStoryPublisher} which corresponds to this object. Publishers provide a common API for pushing object updates into foreign systems.

Other Methods

  • public function setCurrentWorkerTask($task)
  • public function getCurrentWorkerTask()
  • public function getCurrentWorkerTaskID()
  • final protected function doWork() — Doorkeeper workers set up some context, then call @{method:publishFeedStory}.
  • final public function __construct($data)
  • final protected function getTaskData()
  • final protected function getTaskDataValue($key, $default)
  • final public function executeTask()
  • final public static function scheduleTask($task_class, $data, $options)
  • public function renderForDisplay($viewer)
  • public static function setRunAllTasksInProcess($all) — Set this flag to execute scheduled tasks synchronously, in the same process. This is useful for debugging, and otherwise dramatically worse in every way imaginable.
  • final protected function log($pattern)
  • final protected function queueTask($class, $data, $options) — Queue a task to be executed after this one succeeds.
  • final protected function getQueuedTasks() — Get tasks queued as followups by @{method:queueTask}.
  • final public function flushTaskQueue($defaults) — Schedule any queued tasks, then empty the task queue.
  • final public static function awakenTaskIDs($ids) — Awaken tasks that have yielded.
  • protected function newContentSource()
  • protected function loadFeedStory()

Methods

public function getRequiredLeaseTime()
Inherited

PhabricatorWorker

Return the number of seconds this worker needs hold a lease on the task for while it performs work. For most tasks you can leave this at null, which will give you a default lease (currently 2 hours).

For tasks which may take a very long time to complete, you should return an upper bound on the amount of time the task may require.

Return
int|nullNumber of seconds this task needs to remain leased for, or null for a default lease.

public function getMaximumRetryCount()

PhabricatorWorker

Return the maximum number of times this task may be retried before it is considered permanently failed. By default, tasks retry indefinitely. You can throw a PhabricatorWorkerPermanentFailureException to cause an immediate permanent failure.

DoorkeeperFeedWorker

By default, Doorkeeper workers perform a small number of retries with exponential backoff. A consideration in this policy is that many of these workers are laden with side effects.

Return
int|nullNumber of times the task will retry before permanent failure. Return `null` to retry indefinitely.

public function getWaitBeforeRetry($task)

PhabricatorWorker

Return the number of seconds a task should wait after a failure before retrying. For most tasks you can leave this at null, which will give you a short default retry period (currently 60 seconds).

DoorkeeperFeedWorker

See getMaximumRetryCount() for a description of Doorkeeper retry defaults.

Parameters
PhabricatorWorkerTask$taskThe task itself. This object is probably useful mostly to examine the failure count if you want to implement staggered retries, or to examine the execution exception if you want to react to different failures in different ways.
Return
int|nullNumber of seconds to wait between retries, or null for a default retry period (currently 60 seconds).

public function setCurrentWorkerTask($task)
Inherited

This method is not documented.
Parameters
PhabricatorWorkerTask$task
Return
wild

public function getCurrentWorkerTask()
Inherited

This method is not documented.
Return
wild

public function getCurrentWorkerTaskID()
Inherited

This method is not documented.
Return
wild

final protected function doWork()

Doorkeeper workers set up some context, then call publishFeedStory().

Return
wild

final public function __construct($data)
Inherited

This method is not documented.
Parameters
$data
Return
this//Implicit.//

final protected function getTaskData()
Inherited

This method is not documented.
Return
wild

final protected function getTaskDataValue($key, $default)
Inherited

This method is not documented.
Parameters
$key
$default
Return
wild

final public function executeTask()
Inherited

This method is not documented.
Return
wild

final public static function scheduleTask($task_class, $data, $options)
Inherited

This method is not documented.
Parameters
$task_class
$data
$options
Return
wild

public function renderForDisplay($viewer)
Inherited

This method is not documented.
Parameters
PhabricatorUser$viewer
Return
wild

public static function setRunAllTasksInProcess($all)
Inherited

PhabricatorWorker

Set this flag to execute scheduled tasks synchronously, in the same process. This is useful for debugging, and otherwise dramatically worse in every way imaginable.

Parameters
$all
Return
wild

final protected function log($pattern)
Inherited

This method is not documented.
Parameters
$pattern
Return
wild

final protected function queueTask($class, $data, $options)
Inherited

PhabricatorWorker

Queue a task to be executed after this one succeeds.

The followup task will be queued only if this task completes cleanly.

Parameters
string$classTask class to queue.
array$dataData for the followup task.
array$optionsOptions for the followup task.
Return
this

final protected function getQueuedTasks()
Inherited

PhabricatorWorker

Get tasks queued as followups by queueTask().

Return
list<tuple<string, wild, int|null>>Queued task specifications.

final public function flushTaskQueue($defaults)
Inherited

PhabricatorWorker

Schedule any queued tasks, then empty the task queue.

By default, the queue is flushed only if a task succeeds. You can call this method to force the queue to flush before failing (for example, if you are using queues to improve locking behavior).

Parameters
map<string,$defaultswild> Optional default options.
Return
this

final public static function awakenTaskIDs($ids)
Inherited

PhabricatorWorker

Awaken tasks that have yielded.

Reschedules the specified tasks if they are currently queued in a yielded, unleased, unretried state so they'll execute sooner. This can let the queue avoid unnecessary waits.

This method does not provide any assurances about when these tasks will execute, or even guarantee that it will have any effect at all.

Parameters
list<id>$idsList of task IDs to try to awaken.
Return
void

protected function newContentSource()
Inherited

This method is not documented.
Return
wild

protected function loadFeedStory()
Inherited

This method is not documented.
Return
wild

abstract protected function publishFeedStory()

Actually publish the feed story. Subclasses will generally make API calls to publish some version of the story into external systems.

Return
void

abstract public function isEnabled()

Enable or disable the worker. Normally, this checks configuration to see if Phabricator is linked to applicable external systems.

Return
boolTrue if this worker should try to publish stories.

protected function getFeedStory()

Get the PhabricatorFeedStory that should be published.

Return
PhabricatorFeedStoryThe story to publish.

protected function getViewer()

Get the viewer for the act of publishing.

NOTE: Publishing currently uses the omnipotent viewer because it depends on loading external accounts. Possibly we should tailor this. See T3732. Using the actor for most operations might make more sense.
Return
PhabricatorUserViewer.

protected function getPublisher()

Get the DoorkeeperFeedStoryPublisher which handles this object.

Return
DoorkeeperFeedStoryPublisherObject publisher.

protected function getStoryObject()

Get the primary object the story is about, like a DifferentialRevision or ManiphestTask.

Return
objectObject which the story is about.

private function loadPublisher()

Load the DoorkeeperFeedStoryPublisher which corresponds to this object. Publishers provide a common API for pushing object updates into foreign systems.

Return
DoorkeeperFeedStoryPublisherPublisher for the story's object.
Defined
src/applications/doorkeeper/worker/DoorkeeperFeedWorker.php:16
Extends
PhabricatorWorkerFeedPushWorker