Entities

Every domain object in Dispatch embeds a common base type that provides creation and update timestamps.

The base entity

The root dispatch package defines Entity:

type Entity struct {
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
}

IDs are separate, type-safe TypeID values assigned at creation time. See Identity.

Domain entities

Job

Defined in job/job.go. A unit of background work:

type Job struct {
    dispatch.Entity
    ID          id.JobID      `json:"id"`
    Name        string        `json:"name"`
    Queue       string        `json:"queue"`
    Payload     []byte        `json:"payload"`
    State       State         `json:"state"`
    Priority    int           `json:"priority"`
    MaxRetries  int           `json:"max_retries"`
    RetryCount  int           `json:"retry_count"`
    LastError   string        `json:"last_error,omitempty"`
    ScopeAppID  string        `json:"scope_app_id,omitempty"`
    ScopeOrgID  string        `json:"scope_org_id,omitempty"`
    WorkerID    id.WorkerID   `json:"worker_id,omitempty"`
    RunAt       time.Time     `json:"run_at"`
    StartedAt   *time.Time    `json:"started_at,omitempty"`
    CompletedAt *time.Time    `json:"completed_at,omitempty"`
    HeartbeatAt *time.Time    `json:"heartbeat_at,omitempty"`
    Timeout     time.Duration `json:"timeout,omitempty"`
}

Job states:

State	Meaning
`pending`	Waiting to be picked up by a worker
`running`	Currently executing
`completed`	Finished successfully
`retrying`	Failed but scheduled for retry
`failed`	Failed terminally (no more retries)
`cancelled`	Explicitly cancelled

Workflow Run

Defined in workflow/run.go. A single execution of a workflow definition:

type Run struct {
    dispatch.Entity
    ID          id.RunID   `json:"id"`
    Name        string     `json:"name"`
    State       RunState   `json:"state"`
    Input       []byte     `json:"input,omitempty"`
    Output      []byte     `json:"output,omitempty"`
    Error       string     `json:"error,omitempty"`
    ScopeAppID  string     `json:"scope_app_id,omitempty"`
    ScopeOrgID  string     `json:"scope_org_id,omitempty"`
    StartedAt   time.Time  `json:"started_at"`
    CompletedAt *time.Time `json:"completed_at,omitempty"`
}

Run states: running, completed, failed.

Cron Entry

Defined in cron/entry.go. A recurring job schedule:

type Entry struct {
    dispatch.Entity
    ID          id.CronID  `json:"id"`
    Name        string     `json:"name"`
    Schedule    string     `json:"schedule"`
    JobName     string     `json:"job_name"`
    Queue       string     `json:"queue,omitempty"`
    Payload     []byte     `json:"payload,omitempty"`
    ScopeAppID  string     `json:"scope_app_id,omitempty"`
    ScopeOrgID  string     `json:"scope_org_id,omitempty"`
    LastRunAt   *time.Time `json:"last_run_at,omitempty"`
    NextRunAt   *time.Time `json:"next_run_at,omitempty"`
    LockedBy    string     `json:"locked_by,omitempty"`
    LockedUntil *time.Time `json:"locked_until,omitempty"`
    Enabled     bool       `json:"enabled"`
}

DLQ Entry

Defined in dlq/entry.go. A job that exhausted its retry budget:

type Entry struct {
    ID         id.DLQID   `json:"id"`
    JobID      id.JobID   `json:"job_id"`
    JobName    string     `json:"job_name"`
    Queue      string     `json:"queue"`
    Payload    []byte     `json:"payload"`
    Error      string     `json:"error"`
    RetryCount int        `json:"retry_count"`
    MaxRetries int        `json:"max_retries"`
    ScopeAppID string     `json:"scope_app_id,omitempty"`
    ScopeOrgID string     `json:"scope_org_id,omitempty"`
    FailedAt   time.Time  `json:"failed_at"`
    ReplayedAt *time.Time `json:"replayed_at,omitempty"`
    CreatedAt  time.Time  `json:"created_at"`
}

Worker

Defined in cluster/worker.go. A running Dispatch instance in a distributed cluster:

type Worker struct {
    ID          id.WorkerID       `json:"id"`
    Hostname    string            `json:"hostname"`
    Queues      []string          `json:"queues"`
    Concurrency int               `json:"concurrency"`
    State       WorkerState       `json:"state"`
    IsLeader    bool              `json:"is_leader"`
    LeaderUntil *time.Time        `json:"leader_until,omitempty"`
    LastSeen    time.Time         `json:"last_seen"`
    Metadata    map[string]string `json:"metadata,omitempty"`
    CreatedAt   time.Time         `json:"created_at"`
}

Worker states: active, draining, dead.