Iceblock SDK

Open questions

Questions for the app that will use the SDK first. The answers decide what the facade offers and in what order it’s built. Answered ones move to Decided, below.

About the app’s data

  1. What does it keep? Many small records (notes, entries, messages), a few large files (photos, video, recordings), or both? Small records may want a lighter API than files: written often, read whole, watched closely.
  2. Files, or records? Does the app think in paths and folders, or would it rather put and get records by key, with Iceblock keeping each as a file underneath?
  3. One Collection, or several? One for the app, or one per thing it shares (a trip, a project, a family), each with its own group?
  4. How fast must a change reach the others? Iceblock passes a change on within seconds when devices can reach each other, and checks in every ten minutes otherwise (half an hour on mobile data; on a phone in the background, every 15 minutes or so on Wi-Fi and hourly on mobile data). Is that enough, or does the app need something closer to live?
  5. Two people changing the same thing at once. Iceblock takes the latest edit as the file, and keeps the other as a Conflict copy until someone resolves it. Is that right for the app, or should it merge them itself (it would be told of both)?

About sharing

  1. Groups only? Plain share links don’t survive the app being adopted into the user’s network (they name the app’s own network); groups do. Can the app share only through groups?
  2. Who may change things? Do the people an app shares with all write (Contributor), or do some only read (Member)? Who invites: only the person who made the group, or others too?
  3. Approving people. Should someone with an invitation join at once, or does the group’s Owner approve each? The app has to show that question if so.

About the user’s Iceblock

  1. When does the app offer to join it? At first start (“Do you have Iceblock?”), from a setting, or when the app notices Iceblock on the phone?
  2. What should the user see of the app in Iceblock? Its Collection in Files (the default), or hidden there, shown only in Devices under the app?
  3. After joining, who runs the app’s group? The user’s network becomes its home, and an app device can’t change a group itself. Should the app ask for changes (invite, remove) as requests the user approves, or should the user do them in Iceblock?

About the package

  1. Running in the background on Android: sync only while the app is open, or in the background as the Iceblock app does?
  2. Pairing and approval screens: ready-made widgets in the package, or only the data, the app drawing its own?
  3. Linux: a desktop app, a server or command-line tool, or both? A server would want the Rust facade alone.
  4. Publishing: pub.dev and crates.io, or git dependencies on git.tricauda.com? And compiled libraries in the package, or Rust compiled when the app builds?

Decided

The first app’s answers (its needs):

  • Q1, Q2, Q5: immutable records, a new file each, never edited, so no conflicts arise.
  • Q3: one group Collection for what the group shares, and one Collection per network for what’s that network’s own.
  • Q4: the app decides: ordinary changes take the time they take, and the app asks for prompt sync for the ones that matter.
  • Q6: groups only, no plain shares. Q7, Q8: decided by the group’s Owners, with the roles and approvals that exist.
  • Q9: the app offers to join the user’s Iceblock when it finds Iceblock on the device.
  • Q10: the app’s Collections hidden from Files, listed under the group and under Applications.
  • Q11: after adoption, group changes go as requests the user approves.
  • Q12: background sync on Android is needed. Q14: a Linux desktop app.
  • Q13: data only: the app draws its own pairing and approvals.

In the second round: a day’s records rolled up rather than a records API (only finished days, rolled up by the current holder, so no file is ever edited, the day’s records deleted to the trash, not purged); the app’s own invitation URLs; looking for a holder out of touch for two days (the home’s view of last contact; whoever finds it gets it), with coarse presence as a permission of its own (group-contact:<group>: the home hasn’t heard from a member for two days or more), which an app may require without contact; presence counts use of any app built on Iceblock, never saying which, plus last contact, and per device for the app’s own installs within its own network; thresholds of 15 minutes for around, 30 minutes (Wi-Fi) or 90 (mobile data) for recent contact, in 5-minute steps, expiring after two hours; the app builds its own bridge on iceblock-sdk, with the package’s platform parts as a package without Rust.

Decided by Iceblock’s maintainer:

  • No push service (no FCM, no UnifiedPush): delivery to a phone in the background waits for its next background run.
  • Presence is off by default, and only passive: nothing is noted or sent unless an app holds the permission and the user turned it on; it comes from use (when the person last used the app or Iceblock, coarsened), never from watching the device.
  • A cut-down network document for app devices is stage 2: an app knows nothing of Collections outside its scope, not even that they exist. Three permissions the user grants: collections (that the others exist, and their names), devices (your devices’ names) and presence (whether you’re around). Group apps ask for what member networks share in the same way (group-devices:<group>, group-presence:<group>), each member network deciding. Built in r76, as thin app devices: an app holds a view of the network, made for it, never the network’s document.
  • Q15: published on git.tricauda.com, in the iceblock organisation’s Cargo and pub registries, the package carrying the compiled library.

Decided earlier:

  • An app adopted into the user’s network ends as an app device (Scoped), with its Collection in scope. (#326)
  • Adopting an app with its own data is a pulled merge: the user’s device carries it in, and the app never holds the user’s root keys. It’s never joined at Full and lowered after. (#326)
  • Adoption hands the app’s network over to the user’s, with the home of any group the app made; such a group shows in Devices under Applications. (#326) Since amended: the app’s network signs that the user’s succeeds it, and retires its key (#733), every member of its groups is told (r78), and a group has the app among its Applications (#737).
  • An app’s Collections show in Files by default; hiding one is the app’s to ask, and the user’s to change. (#326)
  • The Rust facade and the Flutter package are built together, the package generated from the facade; Android and Linux first. (#326)