

Table of contents

Jobs

Jobs are designed to represent asynchronous tasks that your cozy can execute. These tasks can be scheduled in advance, recurring or sudden and provide various services.

At the time, we do not provide “generic” and programmable tasks. This list of available workers is part of the defined API.

The job queue can be either local to the cozy-stack when used as a monolithic instance (self-hosted for instance) or distributed via a redis server for distributed infrastructures.

This doc introduces two cozy types:

• io.cozy.jobs for jobs
• io.cozy.triggers for triggers

Triggers

Jobs can be queued up via the /jobs/queue/:worker-type API, for a direct execution. But it can also be convenient to schedule jobs on some conditions, and the triggers are the way to do that.

Jobs can be launched by different types of triggers:

• @at to schedule a one-time job executed after at a specific time in the future
• @in to schedule a one-time job executed after a specific amount of time
• @hourly to schedule jobs that run once an hour
• @daily to schedule jobs that run once a day
• @weekly to schedule jobs that run once a week
• @monthly to schedule jobs that run once a month
• @every to schedule periodic jobs executed at a given fix interval
• @cron to schedule recurring jobs scheduled at specific times
• @event to launch a job after a change on documents in the cozy
• @webhook to launch a job when an HTTP request hit a specific URL
• @client when the client controls when the job are launched.

These triggers have specific syntaxes to describe when jobs should be scheduled. See below for more informations.

@at syntax

The @at trigger takes a ISO-8601 formatted string indicating a UTC time in the future. The date is of this form: YYYY-MM-DDTHH:mm:ss.sssZ

Be aware that the @at trigger is removed from the doctype after it has created the associated job.

Examples

@at 2018-12-12T15:36:25.507Z

@in syntax

The @in trigger takes the same duration syntax as @every

Be aware that the @in trigger is removed from the doctype after it has created the associated job.

Examples

@in 10m
@in 1h30m

@daily syntax

The @daily trigger will create a job once a day. By default, the stack is free to choose the day and hour when to do that, but you can add restrictions:

@daily                      # Once a day, any hour
@daily before 5am           # Once a day, between midnight and 5am (UTC)
@daily after 10pm           # Once a day, between 10pm and midnight (UTC)
@daily between 8am and 6pm  # Once a day, between 8am and 6pm (UTC)

@weekly syntax

The @weekly trigger will create a job once a week. By default, the stack is free to choose the day and hour when to do that, but you can add restrictions:

@weekly                      # Once a week, any day, any hour
@weekly on monday            # Every monday
@weekly on mon,wed,fri       # Once a week, on a monday, wednesday, or friday
@weekly on wed-fri           # Once a week, on a wednesday, thursday, or friday
@weekly on weekday           # Once a week, but not the week-end
@weekly on weekend           # Every week-end (saturday or sunday)
@weekly before 5am           # Once a week, any day, but between midnight and 5am (UTC)
@weekly after 10pm           # Once a week, any day, but between 10pm and midnight (UTC)
@weekly between 8am and 6pm  # Once a week, any day, between 8am and 6pm (UTC)
@weekly on monday before 9am # Every monday, between midnight and 9am (UTC)

@monthly syntax

The @monthly trigger will create a job once a month. By default, the stack is free to choose the day and hour when to do that, but you can add restrictions:

@monthly                      # Once a month, any day, any hour
@monthly on the 1             # Every first day of the month
@monthly on the 1-5           # Once a month, on the first five days of the month
@monthly before 5am           # Once a month, any day, but between midnight and 5am (UTC)
@monthly after 10pm           # Once a month, any day, but between 10pm and midnight (UTC)
@monthly between 8am and 6pm  # Once a month, any day, between 8am and 6pm (UTC)
@monthly on the 1 before 9am  # Every first day of the month, between midnight and 9am (UTC)

Note: the current implementation is to take a random day/hour and run the job each month at this day/hour. So, you should avoid 29-31 if you really want the job to run each month.

@every syntax

The @every trigger uses the same syntax as golang’s time.ParseDuration (but only support time units above seconds):

A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as “300ms”, “1.5h” or “2h45m”. Valid time units are “s”, “m”, “h”.

Examples

@every 1.5h   # schedules every 1 and a half hours
@every 30m10s # schedules every 30 minutes and 10 seconds

@cron syntax

In order to schedule recurring jobs, the @cron trigger has the syntax using six fields:

Field name	Mandatory?	Allowed values	Allowed special characters
Seconds	Yes	0-59	* / , -
Minutes	Yes	0-59	* / , -
Hours	Yes	0-23	* / , -
Day of month	Yes	1-31	* / , - ?
Month	Yes	1-12 or JAN-DEC	* / , -
Day of week	Yes	0-6 or SUN-SAT	* / , - ?

Asterisk ( * )

The asterisk indicates that the cron expression will match for all values of the field; e.g., using an asterisk in the 5th field (month) would indicate every month.

Slash ( / )

Slashes are used to describe increments of ranges. For example 3-59/15 in the 1st field (minutes) would indicate the 3rd minute of the hour and every 15 minutes thereafter. The form "*\/..." is equivalent to the form "first-last/...", that is, an increment over the largest possible range of the field. The form "N-/..." is accepted as meaning "N-MAX/...", that is, starting at N, use the increment until the end of that specific range. It does not wrap around.

Comma ( , )

Commas are used to separate items of a list. For example, using "MON,WED,FRI" in the 5th field (day of week) would mean Mondays, Wednesdays and Fridays.

Hyphen ( - )

Hyphens are used to define ranges. For example, 9-17 would indicate every hour between 9am and 5pm inclusive.

Question mark ( ? )

Question mark may be used instead of * for leaving either day-of-month or day-of-week blank.

To schedule jobs given an interval:

Examples:

@cron 0 0 0 1 1 *  # Run once a year, midnight, Jan. 1st
@cron 0 0 0 1 1 *  # Run once a year, midnight, Jan. 1st
@cron 0 0 0 1 * *  # Run once a month, midnight, first of month
@cron 0 0 0 * * 0  # Run once a week, midnight on Sunday
@cron 0 0 0 * * *  # Run once a day, midnight
@cron 0 0 * * * *  # Run once an hour, beginning of hour

@event syntax

The @event syntax allows to trigger a job when something occurs in the stack. It follows the same syntax than permissions scope string:

type[:verb][:values][:selector]

Unlike for permissions string, the verb should be one of CREATED, DELETED, UPDATED. It is possible to put several verbs, separated by a comma.

There is also a special value !=. It means that a job will be trigger only if the value for the given selector has changed (ie the value before the update and the value after that are different).

The job worker will receive a compound message including original trigger_infos messages and the event which has triggered it.

Examples:

@event io.cozy.files // anything happens on files
@event io.cozy.files:CREATED // a file was created
@event io.cozy.files:DELETED:image/jpg:mime // an image was deleted
@event io.cozy.bank.operations:CREATED io.cozy.bank.bills:CREATED // a bank operation or a bill
@event io.cozy.bank.operations:CREATED,UPDATED // a bank operation created or updated
@event io.cozy.bank.operations:UPDATED:!=:category // a change of category for a bank operation

@webhook syntax

It takes no parameter. The URL to hit is not controlled by the request, but is chosen by the server (and is returned as webhook in the links JSON-API response).

Example:

@webhook

@client syntax

It takes no parameter and can only by used for the client worker. The stack won’t create a job unless a client calls the launch endpoint for this trigger. The main goal of this trigger is keep a state, as the aggregation of job results.

Error Handling

Jobs can fail to execute their task. We have two ways to parameterize such cases.

Retry

A retry count can be optionally specified to ask the worker to re-execute the task if it has failed.

Each retry is executed after a configurable delay. The try count is part of the attributes of the job. Also, each occurring error is kept in the errors field containing all the errors that may have happened.

Timeout

A worker may never end. To prevent this, a configurable timeout value is specified with the job.

If a job does not end after the specified amount of time, it will be aborted. A timeout is just like another error from the worker and can provoke a retry if specified.

Defaults

By default, jobs are parameterized with a maximum of 3 tries with 1 minute timeout.

These defaults may vary given the workload of the workers.

Jobs API

Example and description of the attributes of a io.cozy.jobs:

{
  "domain": "me.cozy.localhost",
  "worker": "sendmail",    // worker type name
  "options": {
    "timeout": 60,         // timeout value in seconds
    "max_exec_count": 3,   // maximum number of time the job should be executed (including retries)
  },
  "arguments": {           // the arguments will be given to the worker (if you look in CouchDB, it is called message there)
    "mode": "noreply",
    "template_name": "new_registration",
    "template_values": {
      "DevicesLink": "http://me.cozy.localhost/#/connectedDevices",
    }
  },
  "state": "running",      // queued, running, done, errored
  "queued_at": "2016-09-19T12:35:08Z",  // time of the queuing
  "started_at": "2016-09-19T12:35:08Z", // time of first execution
  "error": ""             // error message if any
}

Example and description of a job creation options — as you can see, the options are replicated in the io.cozy.jobs attributes:

{
  "timeout": 60,         // timeout value in seconds
  "max_exec_count": 3,   // maximum number of retry
}

GET /jobs/:job-id

Get a job informations given its ID.

Request

GET /jobs/123123 HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": {
    "type": "io.cozy.jobs",
    "id": "123123",
    "attributes": {
      "domain": "me.cozy.localhost",
      "worker": "sendmail",
      "options": {
        "timeout": 60,
        "max_exec_count": 3
      },
      "state": "running",
      "queued_at": "2016-09-19T12:35:08Z",
      "started_at": "2016-09-19T12:35:08Z",
      "error": ""
    },
    "links": {
      "self": "/jobs/123123"
    }
  }
}

POST /jobs/queue/:worker-type

Enqueue programmatically a new job.

This route requires a specific permission on the worker-type. A global permission on the global io.cozy.jobs doctype is not allowed.

Each worker accepts different arguments. For konnectors, the arguments will be given in the process.env['COZY_FIELDS'] variable.

Request

POST /jobs/queue/sendmail HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "attributes": {
      "manual": false,
      "options": {
        "timeout": 60,
        "max_exec_count": 3
      },
      "arguments": {} // any json value used as arguments for the job
    }
  }
}

Response

{
  "data": {
    "type": "io.cozy.jobs",
    "id": "123123",
    "attributes": {
      "domain": "me.cozy.localhost",
      "worker": "sendmail",
      "options": {
        "timeout": 60,
        "max_exec_count": 3
      },
      "state": "running",
      "queued_at": "2016-09-19T12:35:08Z",
      "started_at": "2016-09-19T12:35:08Z",
      "error": ""
    },
    "links": {
      "self": "/jobs/123123"
    }
  }
}

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.jobs for the verb POST. The is required to restrict its permission to specific worker(s), like this (a global permission on the doctype is not allowed):

{
  "permissions": {
    "mail-from-the-user": {
      "description": "Required to send mails from the user to his/her friends",
      "type": "io.cozy.jobs",
      "verbs": ["POST"],
      "selector": "worker",
      "values": ["sendmail"]
    }
  }
}

POST /jobs/support

Send a mail to the support (email address defined by mail.reply_to in the config file, or overwritten by context with contexts.<name>.reply_to).

It requires a permission on io.cozy.support (a permission on io.cozy.jobs:POST:sendmail:worker, or larger, is also accepted to ease the transition from sending manually a mail to the support via the sendmail queue).

Request

POST /jobs/support HTTP/1.1
Content-Type: application/vnd.api+json

{
  "data": {
    "attributes": {
      "arguments": {
        "subject": "Cozy is so cool!",
        "body": "I really love Cozy. Thank you so much!"
      }
    }
  }
}

Response

HTTP/1.1 204 No Content

POST /jobs/campaign-emails

Send a non transactional (or campaign) email to the user via the dedicated campaign mail server (configured via campaign_mail attributes in the config file, or overwritten by context with campaign_mail.contexts.<name> attributes).

Both the subject and at least one part are required.

Request

POST /jobs/campaign-emails HTTP/1.1
Content-Type: application/vnd.api+json

{
  "data": {
    "attributes": {
      "arguments": {
        "subject": "Checkout the new cool stuff!",
        "parts": [
          {
            "body": "So many new features to check out!",
            "type": "text/plain"
          }
        ]
      }
    }
  }
}

Response

HTTP/1.1 204 No Content

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.jobs for the verb POST and the sendmail worker. This can be defined like so:

{
  "permissions": {
    "campaign-emails": {
      "description": "Required to send campaign emails to the user",
      "type": "io.cozy.jobs",
      "verbs": ["POST"],
      "selector": "worker",
      "values": ["sendmail"]
    }
  }
}

GET /jobs/queue/:worker-type

List the jobs in the queue.

Request

GET /jobs/queue/sendmail HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "attributes": {
        "domain": "cozy.localhost:8080",
        "options": null,
        "queued_at": "2017-09-29T15:32:31.953878568+02:00",
        "started_at": "0001-01-01T00:00:00Z",
        "state": "queued",
        "worker": "log"
      },
      "id": "77689bca9634b4fb08d6ca3d1643de5f",
      "links": {
        "self": "/jobs/log/77689bca9634b4fb08d6ca3d1643de5f"
      },
      "meta": {
        "rev": "1-f823bcd2759103a5ad1a98f4bf083b36"
      },
      "type": "io.cozy.jobs"
    }
  ],
  "meta": {
    "count": 0
  }
}

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.jobs for the verb GET. In most cases, the application will restrict its permission to only one worker, like this:

{
  "permissions": {
    "mail-from-the-user": {
      "description": "Required to know the number of jobs in the sendmail queues",
      "type": "io.cozy.jobs",
      "verbs": ["GET"],
      "selector": "worker",
      "values": ["sendmail"]
    }
  }
}

PATCH /jobs/:job-id

This endpoint can be used for a job of the client worker (executed by a client, not on the server) to update the status.

Request

PATCH /jobs/022368c07dc701396403543d7eb8149c HTTP/1.1
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.jobs",
    "id": "022368c07dc701396403543d7eb8149c",
    "attributes": {
      "state": "errored",
      "error": "LOGIN_FAILED"
    }
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.jobs",
    "id": "022368c07dc701396403543d7eb8149c",
    "attributes": {
      "domain": "me.cozy.localhost",
      "worker": "sendmail",
      "options": {},
      "state": "errored",
      "error": "LOGIN_FAILED",
      "queued_at": "2021-04-12T12:34:56Z",
      "started_at": "2021-04-12T12:34:56Z",
      "finished_at": "2021-04-12T12:38:59Z"
    },
    "links": {
      "self": "/jobs/022368c07dc701396403543d7eb8149c"
    }
  }
}

POST /jobs/triggers

Add a trigger of the worker. See triggers’ descriptions to see the types of trigger and their arguments syntax.

This route requires a specific permission on the worker type. A global permission on the global io.cozy.triggers doctype is not allowed.

The debounce parameter can be used to limit the number of jobs created in a burst. It delays the creation of the job on the first input by the given time argument, and if the trigger has its condition matched again during this period, it won’t create another job. It can be useful to combine it with the changes feed of couchdb with a last sequence number persisted by the worker, as it allows to have a nice diff between two executions of the worker. Its syntax is the one understood by go’s time.ParseDuration.

Request

POST /jobs/triggers HTTP/1.1
Accept: application/vnd.api+json

{
  "data": {
    "attributes": {
      "type": "@event",
      "arguments": "io.cozy.invitations",
      "debounce": "10m",
      "worker": "sendmail",
      "message": {},
      "options": {
        "timeout": 60,
        "max_exec_count": 3
      }
    }
  }
}

Note: the message field was previously called worker_arguments. The latter version still works but is deprecated, you should use message instead.

Response

{
  "data": {
    "type": "io.cozy.triggers",
    "id": "123123",
    "attributes": {
      "type": "@every",
      "arguments": "30m10s",
      "debounce": "10m",
      "worker": "sendmail",
      "options": {
        "timeout": 60,
        "max_exec_count": 3
      }
    },
    "links": {
      "self": "/jobs/triggers/123123"
    }
  }
}

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.triggers for the verb POST. In most cases, the application will restrict its permission to only one worker, like this:

{
  "permissions": {
    "mail-from-the-user": {
      "description": "Required to send regularly mails from the user to his/her friends",
      "type": "io.cozy.triggers",
      "verbs": ["POST"],
      "selector": "worker",
      "values": ["sendmail"]
    }
  }
}

GET /jobs/triggers/:trigger-id

Get a trigger informations given its ID.

Request

GET /jobs/triggers/123123 HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": {
    "type": "io.cozy.triggers",
    "id": "123123",
    "attributes": {
      "type": "@every",
      "arguments": "30m10s",
      "worker": "sendmail",
      "options": {
        "timeout": 60,
        "max_exec_count": 3
      },
      "current_state": {
        "status": "done",
        "last_success": "2017-11-20T13:31:09.01641731",
        "last_successful_job_id": "abcde",
        "last_execution": "2017-11-20T13:31:09.01641731",
        "last_executed_job_id": "abcde",
        "last_failure": "2017-11-20T13:31:09.01641731",
        "last_failed_job_id": "abcde",
        "last_error": "error value",
        "last_manual_execution": "2017-11-20T13:31:09.01641731",
        "last_manual_job_id": "abcde"
      }
    },
    "links": {
      "self": "/jobs/triggers/123123"
    }
  }
}

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.triggers for the verb GET. A konnector can also call this endpoint for one of its triggers (no permission required).

GET /jobs/triggers/:trigger-id/state

Get the trigger current state, to give a big picture of the health of the trigger.

• last executed job status (done, errored, queued or running)
• last executed job that resulted in a successful executoin
• last executed job that resulted in an error
• last executed job from a manual execution (not executed by the trigger directly)

Request

GET /jobs/triggers/123123/state HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": {
    "type": "io.cozy.triggers.state",
    "id": "123123",
    "attributes": {
      "status": "done",
      "last_success": "2017-11-20T13:31:09.01641731",
      "last_successful_job_id": "abcde",
      "last_execution": "2017-11-20T13:31:09.01641731",
      "last_executed_job_id": "abcde",
      "last_failure": "2017-11-20T13:31:09.01641731",
      "last_failed_job_id": "abcde",
      "last_error": "error value",
      "last_manual_execution": "2017-11-20T13:31:09.01641731",
      "last_manual_job_id": "abcde"
    }
  }
}

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.triggers for the verb GET. A konnector can also call this endpoint for one of its triggers (no permission required).

GET /jobs/triggers/:trigger-id/jobs

Get the jobs launched by the trigger with the specified ID.

Query parameters:

• Limit: to specify the number of jobs to get out

Request

GET /jobs/triggers/123123/jobs?Limit=1 HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "io.cozy.jobs",
      "id": "123123",
      "attributes": {},
      "links": {
        "self": "/jobs/123123"
      }
    }
  ]
}

PATCH /jobs/triggers/:trigger-id

This route can be used to change the frequency of execution of a @cron trigger, or the message of any trigger.

Request

PATCH /jobs/triggers/123123 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "attributes": {
      "type": "@cron",
      "arguments": "0 0 0 * * 0"
    }
  }
}

Response

{
  "data": {
    "type": "io.cozy.triggers",
    "id": "123123",
    "attributes": {
      "type": "@cron",
      "arguments": "0 0 0 * * 0",
      "worker": "sendmail",
      "options": {
        "timeout": 60,
        "max_exec_count": 3
      }
    },
    "links": {
      "self": "/jobs/triggers/123123"
    }
  }
}

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.triggers for the verb PATCH. A konnector can also call this endpoint for one of its triggers (no permission required).

POST /jobs/triggers/:trigger-id/launch

Launch a trigger manually given its ID and return the created job.

Note: this endpoint can be used to create a job for a @client trigger. In that case, the job won’t be executed on the server but by the client. And the client must call PATCH /jobs/:job-id when the job is completed (success or error).

Request

POST /jobs/triggers/123123/launch HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": {
    "type": "io.cozy.jobs",
    "id": "123123",
    "attributes": {
      "domain": "me.cozy.localhost",
      "worker": "sendmail",
      "options": {},
      "state": "running",
      "queued_at": "2016-09-19T12:35:08Z",
      "started_at": "2016-09-19T12:35:08Z",
      "error": ""
    },
    "links": {
      "self": "/jobs/123123"
    }
  }
}

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.triggers for the verb POST.

DELETE /jobs/triggers/:trigger-id

Delete a trigger given its ID.

Request

DELETE /jobs/triggers/123123 HTTP/1.1
Accept: application/vnd.api+json

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.triggers for the verb DELETE. A konnector can also call this endpoint for one of its triggers (no permission required).

GET /jobs/triggers

Get the list of triggers. This route only accept Worker and Type query parameters and returns the trigger but also in attributes its current_state (the same current_state returned by GET /jobs/triggers/:trigger-id). Be warned that /data/io.cozy.triggers/_find does not return this current_state attribute and you’ll need to query /jobs/triggers/:trigger-id to have it.

Query parameters (with comma-separated values):

• Type: to filter on the trigger type (@cron, @in, etc.)
• Worker: to filter only triggers associated with a specific worker.

Request

GET /jobs/triggers?Worker=konnector&Type=@cron,@in,@at HTTP/1.1
Accept: application/vnd.api+json

Response

{
  "data": [
    {
      "type": "io.cozy.triggers",
      "id": "123123",
      "arguments": "0 40 0 * * *",
      "current_state": {
        "last_error": "LOGIN_FAILED",
        "last_executed_job_id": "abc",
        "last_execution": "2019-01-07T08:23:22.069902888Z",
        "last_failed_job_id": "abcd",
        "last_failure": "2019-01-07T08:23:22.069902888Z",
        "last_manual_execution": "2019-01-07T08:23:22.069902888Z",
        "last_manual_job_id": "azer",
        "status": "errored",
        "trigger_id": "123123"
      },
      "debounce": "",
      "domain": "xxx.mycozy.cloud",
      "message": {
        "konnector": "slug",
        "account": "XXX"
      },
      "options": null,
      "type": "@cron",
      "worker": "konnector",
      "id": "123123",
      "links": {
        "self": "/jobs/triggers/123123"
      }
    }
  ]
}

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.triggers for the verb GET. When used on a specific worker, the permission can be specified on the worker field.

POST /jobs/webhooks/:trigger-id

This endpoint is used for creating a job (for example executing a konnector or a service). It requires no permission, but a trigger of type @webhook must have been created before using this endpoint. Its body must be a JSON that will be available to the konnector or to the service through the process.env['COZY_PAYLOAD'] variable.

It is possible to pass a Manual=true parameter in the query-string if the job is interactive. It will give it an higher priority in the queues.

Request

POST /jobs/webhooks/f34c74d0-0c91-0139-5af5-543d7eb8149c HTTP/1.1
Content-Type: application/json

{
  "account_id": "0672e560"
}

Response

HTTP/1.1 204 No Content

POST /jobs/webhooks/bi

This endpoint is used to create jobs for banking konnectors. It requires a payload with the format defined by Budget Insight and an Authorization header with a Bearer token, where a trigger and an account can be found on this instance matching their data. The event type and the URL of the BI API (on the good environment) are also sent in the query string.

Request

POST /jobs/webhooks/bi?event=CONNECTION_SYNCED&bi_url=https://.../ HTTP/1.1
Content-Type: application/json
Authorization: Bearer token-from-bi
Host: cozy.example.com

Response

HTTP/1.1 204 No Content

DELETE /jobs/purge

This endpoint allows to purge old jobs of an instance. Some parameters can be given to this route:

• duration is the duration of jobs to keep. This is a human-readable string (integer+suffix). For example:
• “3W” will keep jobs up to 3 weeks
• “2M” will keep jobs up to 2 months
• workers is a comma-separated list of workers to apply the purge job.

Request

DELETE /jobs/purge HTTP/1.1
Accept: application/json

Response

{
  "deleted": 42
}

Permissions

To use this endpoint, an application needs a permission on the type io.cozy.jobs for the verb DELETE.

Worker pool

The consuming side of the job queue is handled by a worker pool.

On a monolithic cozy-stack, the worker pool has a configurable fixed size of workers. The default value is not yet determined. Each time a worker has finished a job, it check the queue and based on the priority and the queued date of the job, picks a new job to execute.

Permissions

In order to prevent jobs from leaking informations between applications, we may need to add filtering per applications: for instance one queue per applications.

We should also have an explicit check on the permissions of the applications before launching a job scheduled by an application. For more information, refer to our permission document.

Multi-stack

When some instances are served by several stacks, the scheduling and running of jobs can be distributed on the stacks. The synchronization is done via redis.

For scheduling, there is one important key in redis: triggers. It’s a sorted set. The members are the identifiants of the triggers (with the domain name), and the score are the timestamp of the next time the trigger should occur. During the short period of time where a trigger is processed, its key is moved to scheduling (another sorted set). So, even if a stack crash during processing a trigger, this trigger won’t be lost.

For @event triggers, we don’t use the same mechanism. Each stack has all the triggers in memory and is responsible to trigger them for the events generated by the HTTP requests of their API. They also publish them on redis: this pub/sub is used for the realtime API.