mesh-contracts/seats/node-backup/seat.json

{
  "format": 1,
  "seat": "node-backup",
  "scope": "node",
  "grain": "seat-list",
  "domain": "Data",
  "decision": "novox/hq ADR 0214",
  "verbs": [
    {
      "name": "backed-up",
      "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size.",
      "replaces": [
        "restic snapshots"
      ],
      "input": {
        "properties": {
          "module": {
            "description": "one module (optional)",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    {
      "name": "now",
      "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong.",
      "replaces": [
        "restic backup"
      ],
      "input": {
        "properties": {
          "module": {
            "description": "one module (optional)",
            "type": "string"
          }
        },
        "type": "object"
      },
      "class": "act"
    },
    {
      "name": "restore",
      "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as <path>.restored-<date>. Swapping it in is a person's act. Lists the restore points when none is named.",
      "replaces": [
        "restic restore"
      ],
      "input": {
        "properties": {
          "module": {
            "description": "the module",
            "type": "string"
          },
          "path": {
            "description": "one of the module's directories (all of them when omitted)",
            "type": "string"
          },
          "snapshot": {
            "description": "the restore point (from `backed-up`; the newest when omitted)",
            "type": "string"
          }
        },
        "required": [
          "module"
        ],
        "type": "object"
      },
      "class": "act"
    }
  ],
  "events": [
    {
      "name": "item-started",
      "subject": "item-started.<node>.<module>.<item>",
      "keep": {
        "max-age-days": 7,
        "last-per-subject": true
      },
      "body": {
        "type": "object",
        "description": "the holder started backing up one item of a module on its node, said before it reads the recovery module's restore-started and restored (design 47 G 554, 563)",
        "required": [
          "at"
        ],
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "when the item started, RFC 3339"
          }
        }
      }
    },
    {
      "name": "item-ended",
      "subject": "item-ended.<node>.<module>.<item>",
      "keep": {
        "max-age-days": 7,
        "last-per-subject": true
      },
      "body": {
        "type": "object",
        "description": "the holder ended one item: done, failed (error stopped for an item it said started and never ended, at its start) or put-off while a restore of the recovery module runs, the item started again when that restore's restored is heard (design 47 G 554, 563)",
        "required": [
          "at",
          "outcome"
        ],
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "when the item ended, RFC 3339"
          },
          "outcome": {
            "type": "string",
            "enum": [
              "done",
              "failed",
              "put-off"
            ],
            "description": "how the item ended; a put-off item is that night's backup once it runs, neither failed nor missed"
          },
          "restore": {
            "type": "string",
            "description": "with put-off, the act of the recovery module's restore the item gave way to"
          },
          "error": {
            "type": "string",
            "description": "with failed, why, in words; stopped for an item ended at the holder's start"
          }
        }
      }
    }
  ],
  "receives": [
    {
      "kind": "backup",
      "comment": "#",
      "dirs": true
    },
    {
      "kind": "data",
      "comment": "#",
      "dirs": true
    }
  ]
}