osprey: write json spec about aviary

[rabsef-bicrym]

Osprey

Osprey is a mixture of Peat, Expo and Doombot. If you take a device intended for
murder, and add to it some administrative overhead, you get a bird of prey. thus

NOTE: though osprey has the ability to backup dms and clubs, it does not have the ability to restore those messages built in. they are stored in a different format and the business logic for restoring them is not perfectly clear. i will discuss with tlon later. please do not implement features for backing up / restoring dms at this time.

+on-watch:

watch on /web-ui to get your facts. you'll get an initial load of facts that mirror those you find in +on-peek.

+on-peek:

• /dms

  • get existing DMs

  {
    "type": "SCRY",
    "face": "OSPREY-HOSTED-DMS",
    "fact": [
      "~zod",
      "~wet",
      "~nut"
    ]
  }

• /chats

  • get existing chats

  {
    "type": "SCRY",
    "face": "OSPREY-HOSTED-CHAT",
    "fact": [
      "~zod/test-chat",
      "~zod/test-chat-2",
      "~zod/test-chat-3"
    ]
  }

• /heaps

  • get existing heaps

  {
    "type": "SCRY",
    "face": "OSPREY-HOSTED-HEAPS",
    "fact": [
      "~zod/test-heap",
      "~zod/test-heap-2",
      "~zod/test-heap-3"
    ]
  }

• /groups

  • get existing groups

  {
    "type": "SCRY",
    "face": "OSPREY-HOSTED-GROUPS",
    "fact": [
      "~zod/group",
      "~zod/group-2",
      "~zod/group-3"
    ]
  }

• /diaries

  • get existing groups

  {
    "type": "SCRY",
    "face": "OSPREY-HOSTED-DIARIES",
    "fact": [
      "~zod/test-diary",
      "~zod/test-diary-2",
      "~zod/test-diary-3"
    ]
  }

• /schedule

  • get existing groups

  {
    "type": "SCRY",
    "face": "OSPREY-STATE-SCHEDULE",
    "fact": [
      "~zod/group",
      "~zod/group-2",
      "~zod/group-3"
    ]
  }

+on-poke:

you can perform the following actions

• archive an archive backs up an existing channel, once.
  • [%mine ~] - all channels you host
  • [%heap [ship term]] - a specific heap
  • [%chat [ship term]] - a specific chat
  • [%diary [ship term]] - a specific diary
  • [%group [ship term]] - the resources in a specific group

Note: strongly encourage users to utilize [%mine ~] on a discretionary basis, e.g. full system failure. While it's fine to use [%mine ~] on a recurring basis, it might take a lot of system resources.
Note: currently there is no protection for rapid recurring output - this will be added in for the user at no more often than ever 12 hours. For testing purposes, you can put in a few minutes (no less than 1 minute).

• repeat set an archive repetition schedule, or cancel it.
• doom kick people who haven't been seen for some time.
• boot kick (but do not ban) those ships attached to a group, of a given rank.
• restore restore a chat from backup - note this isn't a poke, only file upload.

archive

• poke:
  • mine:

    {
      "mine": null
    }

  • heap:

    {
      "heap": "~zod/test-heap"
    }

  • diary:

    {
      "diary": "~zod/test-diary"
    }

  • group:

    {
      "group": "~zod/my-group"
    }

  • chat:

    {
      "chat": {
        "flag": "~zod/a-chat" ||,
        "ship": "~wet" ||,  //a dm
        "club": "0v123456"  //a club
      }
    }

  • response (immediate):

    {
      "type": "FACT",
      "face": "ARCHIVE-START",
      "fact": {
        "what": <an archive json as above in the poke section>
      }
    }

  • response (incremental):

    {
      "type": "FACT",
      "face": "ARCHIVE-STATUS-UPDATE",
      "fact": {
        "archiving": <an archive json as above in the poke section>,
        "total": 10,   // count of total jam files to be produced, roughly
        "complete": 8, // count of completed jams
        "done": FALSE  // will print as true when complete
      }
    }

repeat

• poke:

  {
    "repeat": {
      "arc": { "mine": null },  // or some other arrangement
      "oft": 1000 // every x seconds
    }
  }

doom

• poke:

  {
    "doom": {
      "limit": 10, //only allow for kicking up to 10 users
      "age": 1000, //limit for QOS kick - this case would be people last seen more than 1000 seconds ago,
      "group": "~zod/this-group"
    }
  }

• response (instant):

  {
    "type": "FACT",
    "face": "DOOMING",
    "fact": {
      "seconds": 1000,
      "group": "~zod/this-group"
    }
  }

• repsonse (complete):

  {
    "type": "FACT",
    "face": "DOOMBOT-RESULTS",
    "fact": {
      "killed": ["~zod" "~wet"],
      "group": "~zod/this-group"
    }
  }

boot

• poke

  {
    "boot": {
      "rank": "pawn", // or czar king duke earl see 4938 of zuse
      "group": "~zod/test-group"
    }
  }

• response (instant):

  {
    "type": "FACT",
    "face": "DOOMING",
    "fact": {
      "rank": "pawn",
      "group": "~zod/this-group"
    }
  }

• response (complete):

  {
    "type": "FACT",
    "face": "BOOTBOT-RESULTS",
    "fact": {
      "killed": "pawn",
      "group": "~zod/this-group"
    }
  }