The frappe → Nextcloud calendar bridge
Status: open design. Phase 1 shipped, and phase 2 is built in part (2026-08-10). Phase 1 (§9.1) exists in full:
apps/platform/frappe/nextcloud.plug.yaml, the calendar growth ofapps/collaboration/nextcloud/nextcloud.socket.yaml, and the bench app atgitlab.com/bitspur/frappe/nextcloud(baked as a digest-pinned registry tarball). Phase 2 (§9.2) is built to exactly the line the owed rulings draw; see the status note in §9.2: the ledger, theUserdoc events, thehourly_longsweep and per-user generation revocation are in the bench app at commit8b3ee4d(v0.2.0), and the provider-side job understands a revoked URL’s410+X-SHC-Feed-Generationanswer. The effector rung is stillRULING OWED(nothing consumer-side writes toward Nextcloud), anduser_removeddetection still waits on both an observer and ruling §11.1; the state exists in the schema and nothing sets it.
Replaces §2 of 2026-08-08-identity-and-edge-brokers.md, which held the stub open pending those probes.
0. Measured, specified, owed
Section titled “0. Measured, specified, owed”Every claim in this document belongs to exactly one of three classes, and the class is stated at every use. Read this table before quoting anything.
| Class | Meaning | Marked |
|---|---|---|
| MEASURED | Probed against a live Nextcloud, 2026-08-08/09 | plain statement, dated |
| SPECIFIED | This document decides it; no code exists | ”the app MUST…” |
| VERIFY | A concrete assumption with the one command that settles it | VERIFY |
| RULING OWED | An owner decision, not an agent’s to make | RULING OWED |
MEASURED, and the whole reason this document exists:
- The server-side write surface exists.
occ dav:create-subscription <user> <name> <url> [color],occ dav:list-subscriptions <user>,occ dav:delete-subscription. There is no update command; changing a subscription’s URL is delete + recreate. There is no per-subscription refresh rate at create time. - The cadence knob is app config:
dav.calendarSubscriptionRefreshRate. Unset falls through to the code defaultP1D. A writtenPT5Msticks and takes effect;RefreshWebcalJobauto-registers per subscription and pulls the events. Proven end to end. - Nextcloud refuses in-fabric feed hosts by default. Fetching a feed from
a host on a private range needs
allow_local_remote_servers=true, and frappe will be in-fabric. dav:create-subscription’s exact semantics, read off the pinned 34.0.2 image (apps/dav/lib/Command/CreateSubscription.php) by the socket-growth work in flight beside this document; see the note below:- it dedupes on the source URL, not the display name, and it fails (exit 1, “Subscription for url … already exists for this user”) rather than no-op. A converger must read that as success;
dav:delete-subscription <uid> <uri>takes the uri thatdav:list-subscriptions <uid>prints in its first column, never the display name;- the color argument defaults to the theme’s primary when omitted.
★ A concurrent, uncommitted change is growing nextcloud.socket.yaml in
this same worktree: an opt-in per-consumer admin grant (occ user:auth-tokens:add on the admin account, mint-and-returned), plus ocsUrl,
adminUser and a read-back calendarRefreshRate. This document is written
against that shape rather than around it. Two of its conclusions come
straight from that work (the semantics above, and §7’s refusal to write the
cadence knob from an edge), and where the two designs met independently on the
same three phase-2 write paths (§9.2) that agreement is worth more than either
statement alone.
The gap that closes: §2 of the 2026-08-08 doc said the Nextcloud side might
need “a ~10-line admin-authed endpoint in a helper store app”. For phase 1 it
does not. occ is enough, and occ is reachable from exactly one place,
which is what fixes every placement decision in §4.
1. What the bridge is for
Section titled “1. What the bridge is for”ERPNext holds the work calendar: the meeting booked off a Lead, the site visit on a Project, the interview on a Job Applicant. Nextcloud holds the personal calendar and is the thing already federated into every user’s phone and laptop. Today those are two windows, and the ERPNext one is only open while a browser tab is.
The bridge makes each user’s ERPNext events show up in their Nextcloud calendar list, without that user pasting a URL, without an admin creating anything per person, and without ERPNext events becoming editable in a place ERPNext cannot see.
One-way, read-only, ERPNext → Nextcloud. Nothing a user does in Nextcloud travels back. That is not a v1 shortcut deferred for later: a writable mirror makes Nextcloud a second author of a document ERPNext owns, and the merge question that follows has no good answer at this altitude.
2. Topology: a webcal subscription, not a CalDAV push
Section titled “2. Topology: a webcal subscription, not a CalDAV push”Two designs reach “the user sees ERPNext events in Nextcloud”. The estate has one of each on the table, and they are not variations; they invert who does the work.
A. CalDAV push (bridges/huly-nextcloud) | B. webcal subscription (this doc) | |
|---|---|---|
| who writes events | the bridge, PUT per event, If-Match on a recorded ETag | nobody; Nextcloud GETs one ICS document |
| who owns the collection | a service account; the human is a read-only sharee | the human owns the subscription |
| per-event state | one row per event (uid, etag, last push) | none |
| a deleted event | needs a DELETE the bridge must not miss | disappears from the next fetch |
| a 6-hour bridge outage | events silently stale until it returns; the ledger heals | the feed is computed at fetch time, so nothing was ever stale |
| credentials needed | one service account, or per-user app passwords | none in phase 1 |
| freshness | seconds (push) | the refresh rate (§7) |
| write surface required | full CalDAV against another principal | one occ invocation, once per user, ever |
B, and the deciding argument is the fourth row. A push bridge’s ledger exists because the representation lives on the far side and can drift from the source; a subscription has no far-side representation to drift. What is still needed per user is a subscription object, created once, then inert. That collapses the ledger from “one row per event, forever” to “one row per user, written twice”.
huly-nextcloud reached A for a reason that does not apply here: Huly’s source of truth is a transaction queue with no queryable “all events for user X at time T” view, so a push was the only shape available. Frappe has a database and a web worker; it can answer that query on demand.
What B gives up, honestly: freshness is polled, not pushed (§7); the subscription is an object the user owns and can delete (§6.4); and the feed URL is a bearer capability in a query string (§5.3).
3. What Nextcloud’s occ surface actually constrains
Section titled “3. What Nextcloud’s occ surface actually constrains”Three constraints follow directly from the measured surface, and each one removes an option that would otherwise look reasonable.
3.1 No update command ⇒ a URL change is a delete + recreate
Section titled “3.1 No update command ⇒ a URL change is a delete + recreate”The subscription’s source cannot be edited from occ. Any change to the
feed’s origin, path, query shape or token forces the pair. Consequences:
- The user-visible object is destroyed and rebuilt. Whatever the user did to that calendar in the Nextcloud UI, renamed it, recolored it, hid it from the month view, is client-side state keyed on the collection, and it does not survive. URL churn is user-visible damage, not a no-op.
- The order must be create-then-delete, never delete-then-create. A failed create after a successful delete leaves the user with nothing and the job with no way to tell that state apart from “never subscribed”. Create the new subscription, read it back, then delete the one carrying the old source. A brief duplicate is the cost, and it is much the cheaper failure.
- Therefore the URL is designed to be stable for the life of the deployment (§5.3): no version segment, no scheduled token rotation, and the origin stated once as an operator variable rather than derived from anything that moves.
Two measured details make the code that does this shorter than the paragraph
above suggests. dav:create-subscription dedupes on the source URL and
exits 1 when that URL is already subscribed for the user, so the converger
needs no “does it exist” query on the happy path at all: it creates, and reads
the failure as converged. And dav:delete-subscription takes the uri
from dav:list-subscriptions’ first column, not the display name, so the
display name stays purely human and is never part of any identifier.
3.2 No per-subscription refresh rate ⇒ the cadence knob is instance-wide
Section titled “3.2 No per-subscription refresh rate ⇒ the cadence knob is instance-wide”dav.calendarSubscriptionRefreshRate is app config on dav. Writing it
changes the refresh interval of every subscription on the instance,
including ones users added themselves; a household holiday feed that
refreshed daily now refreshes 96 times a day if the bridge sets PT15M. §7.2
is why the bridge does not set it at all.
3.3 occ is reachable from exactly one place
Section titled “3.3 occ is reachable from exactly one place”occ is a PHP CLI inside the Nextcloud container. Nothing in the frappe stack
can invoke it, and SHC offers no cross-stack request-time exec: the
in-stack exec broker proposal (itself
unbuilt) lists “cross-stack or cross-tenant targets” among its hard nos. So
every subscription write happens in a provider-side job, and the only
question left is who tells that job what to write.
4. The five mechanics that fix every placement decision
Section titled “4. The five mechanics that fix every placement decision”These are properties of the engine, not preferences. Each one was learned the expensive way somewhere else in the catalogue.
4.1 A provider-side socket job is the only thing that can run occ.
Follows from §3.3. jobs.integration on nextcloud.socket.yaml execs into the
nextcloud service; a plug’s post_deployment job execs into a consumer
service.
4.2 A consumer plug’s post_deployment job cannot read a minted value.
runConsumerPlugPostDeploymentJobs builds its context from the statically
rendered socket data; MergeJobMintedValues writes into the map the compose
and hook render reads. apps/devops/sonarqube/gitlab.plug.yaml documents the
whole mechanism, and it is why SonarQube’s GitLab work lives in app.yaml
hooks. Consequence here: any consumer-side job that needs a Nextcloud
credential must be a post_install/post_update hook job, not a plug job. In
phase 1 no such credential exists, so this constraint costs nothing; it is
recorded because phase 2 walks straight into it.
4.3 On a fresh install the consumer is not up when the socket’s integration
jobs run; on an update it is. Phase order is discovery → integration
(provider) → compose up (consumer) → post_deployment (consumer) →
post_install hooks. On shc update the old containers still serve while
phases 1–2 run (the same property that makes pre_update the only gate that
can refuse safely, X409005HKGATE). So a provider-side job that dials the
consumer works on every update and defers on a first install. §9.1 makes
that deferral an explicit, loud, actionable state rather than a failure.
4.4 The provider reaches the consumer by short service alias. Attaching a
consumer service to the provider’s network publishes that service’s short
name as a DNS alias on it (docs/app-development/plugs-and-sockets.md, the
services: pin). So from the Nextcloud container, a frappe stack that pinned
services: [frappe-web] is reachable at http://frappe-web:8000. The
hazard is in the same sentence: two frappe stacks bound to one Nextcloud both
publish frappe-web, Docker round-robins, and half the subscriptions point at
the wrong bench. §8.1 turns that into an identity check rather than a warning.
4.5 Crons see no integrations. A job run outside an install builds no
integrations namespace (the same fact that makes SonarQube’s hook jobs no-op
on a bare hook run). So a crons: entry on the Nextcloud stack cannot read the
plug data it would need. VERIFY: read execute_job_task’s render context
before relying on the negative; if it holds, a cron-driven backfill needs the
edge’s parameters persisted somewhere the cron can read, which is a phase-2
design and not a phase-1 shortcut.
5. The bench app: frappe_nextcloud
Section titled “5. The bench app: frappe_nextcloud”It does not exist. What follows is its specification.
5.1 Name, home, and why one app rather than two
Section titled “5.1 Name, home, and why one app rather than two”frappe_nextcloud, module Nextcloud Bridge, repo
gitlab.com/bitspur/frappe/nextcloud (the bitspur/frappe/* convention
frappe_keycloak already follows).
One app per provider edge, not one per feature. The estate already has a
second frappe↔Nextcloud need in flight: the file picker’s frappe shim
(bridges/nextcloud-picker/frappe-shim/). Under the bake rule (§8.5) every new
bench app is an image rebuild plus a pin bump plus a provenance assertion,
forever. Two apps for one edge doubles that cost permanently, and the plug is
one plug. The calendar bridge is the first module inside frappe_nextcloud;
the picker shim is the second when it lands.
Precedents for the shape, both in bridges/: frappe_medusa (doc events →
enqueue → converge, scheduler sweep, per-object map doctypes) and
erpnext_keycloak (provenance markers, a write boundary enforced by a test).
This app is smaller than either.
5.2 What it serves
Section titled “5.2 What it serves”One endpoint. frappe.whitelist(allow_guest=True) on a GET:
GET <feedBase>/api/method/frappe_nextcloud.api.feed?u=<email>&t=<token>The status codes are a contract, because §6.1 makes the provider-side job read them as the both-ends-exist test:
| Code | Meaning | What the socket job does |
|---|---|---|
200 text/calendar | both ends exist; body is the user’s VCALENDAR | create or converge the subscription |
| 404 | no enabled ERPNext user with that email | skip; delete an existing subscription for this edge |
| 401 | the token does not verify | refuse loudly; this is a misconfigured secret, never a missing user |
| 429 | rate limited | defer, change nothing |
| connection refused / DNS failure | frappe is not up | defer, change nothing |
The app MUST set frappe.local.response["http_status_code"] explicitly on
every branch. VERIFY at implementation: frappe’s default is to answer 200
with an error payload for several failure shapes, which would make a missing
user read as “subscribe them”.
The response MUST carry ETag (a hash of the rendered body) and honor
If-None-Match with a 304. Nextcloud’s refresh is a plain GET per interval per
subscription; a 304 makes the steady state nearly free.
@rate_limit-decorate the endpoint. VERIFY the import path in frappe v15.
5.3 The auth model: a tokenized URL, and why not a bearer
Section titled “5.3 The auth model: a tokenized URL, and why not a bearer”Decision: a capability token in the URL, derived by HMAC. Not a bearer header, and not an API key.
The argument is mechanical before it is anything else: a Nextcloud
subscription has exactly one field that can carry a secret: the source URL.
dav:create-subscription takes user, name, URL and color. There is no header
map, no credential reference, and no place to put an Authorization value.
RefreshWebcalJob fetches the stored URL. A bearer token has nowhere to live,
so the choice is between a token in the URL and no authentication at all.
Not the alternatives:
- Not frappe’s
api_key:api_secret. That credential is account-wide REST access for the user it belongs to. Putting it in a URL that lands in a database column any Nextcloud admin can read, and in the user’s own browser when the Calendar app shows the subscription’s source, would trade a calendar for an ERP session. - Not “unauthenticated, it’s only calendars”. A user’s meeting subjects are the shape of their work: customers, candidates, disputes. An unauthenticated per-user feed is an enumeration oracle over the whole staff.
The token shape:
t = base32( HMAC-SHA256( feedSecret, "<lowercased-email>|<generation>" ) )[:32]feedSecretis one deployment-wide secret,ref+vault://calendar_feed_secret?autogen, never auto-rotated. Both ends compute from it: the bench app to verify, and the provider-side job to construct the URL without asking frappe anything. That second property is what makes phase 1 possible with no ledger and no enumeration endpoint.generationis per user, default1, read from the ledger when the ledger exists (§5.6) and assumed1when it does not. Bumping it is how a single user’s feed is revoked, and because the URL changes, revocation is correctly expressed as a delete + recreate (§3.1). This is whygenerationis in the HMAC input from day one and never in the query string: adding it later would change every URL in the estate at once.- Verification is a constant-time compare of the recomputed value.
What this leaks, stated plainly. The token appears in the frappe web
server’s access log, in Nextcloud’s oc_calendarsubscriptions.source column,
and in the subscription’s own detail view for the user who owns it. The first
is the only one that matters, and the blast radius of the leak is one user’s
calendar, read-only, revocable by a generation bump. That is an acceptable
trade for a capability that cannot be expressed any other way; it would not be
acceptable for a credential with any write scope, which is exactly why the
token grants none.
The email in the URL is deliberate: it makes verification stateless on both ends. An opaque token that must be looked up requires an index, and an index requires the ledger to exist before the first subscription can be created, which is the dependency phase 1 exists to avoid.
5.4 What it watches
Section titled “5.4 What it watches”doc_events, in hooks.py, in two families with two different purposes:
doc_events = { "User": { "after_insert": "frappe_nextcloud.calendar.tasks.on_user_changed", "on_update": "frappe_nextcloud.calendar.tasks.on_user_changed", "on_trash": "frappe_nextcloud.calendar.tasks.on_user_trashed", }, "Event": { "after_insert": "frappe_nextcloud.calendar.tasks.touch_feed", "on_update": "frappe_nextcloud.calendar.tasks.touch_feed", "on_trash": "frappe_nextcloud.calendar.tasks.touch_feed", },}★ The Event hooks are a cache concern, not a correctness concern, and
saying so is the point. In a push bridge, missing an event hook means the far
side is permanently wrong. Here the feed is computed at fetch time, so a missed
hook costs nothing but a stale ETag. touch_feed bumps a per-user feed
version so the 304 path stays honest; a bug in it degrades to “the ETag always
changes”, never to “an event is missing”. Nothing in this app enqueues a write
to Nextcloud from an Event hook, and nothing should.
The User hooks are the ones that matter, and only in phase 2: a new or
newly-enabled user is the moment a subscription becomes possible, and a
disabled or deleted user is the moment it must go away.
scheduler_events (phase 2) run the level-triggered sweep; hourly_long is
the right rung; the medusa precedent uses */5 for a poll that has a queue
behind it, and this one does not.
VERIFY: the frappe stack runs bench schedule (confirmed in
apps/platform/frappe/compose.yaml), but a site can still carry
pause_scheduler/scheduler_enabled from a restore; frappe.exporter.yaml
already names both as source-deployment posture that a restore must not carry
in. A phase-2 preflight must assert the scheduler is live, because a paused
scheduler makes the loop silently stop converging.
5.5 What it writes into Nextcloud
Section titled “5.5 What it writes into Nextcloud”In phase 1: nothing. The provider-side job owns every write. The bench app is a read surface and a secret verifier.
In phase 2 it needs an effector, and that is the one genuinely open design question in this document, §9.2.
5.6 The ledger (phase 2)
Section titled “5.6 The ledger (phase 2)”One doctype, Nextcloud Calendar Link, one row per ERPNext user. Named
hash, permissions System Manager only, track_changes off.
| field | type | why |
|---|---|---|
user | Link → User, unique, reqd | the ERPNext end |
match_email | Data | lowercased; what the match was made on, frozen |
nc_user_id | Data | the Nextcloud uid, empty until observed |
generation | Int, default 1 | the revocation counter of §5.3 |
state | Select | pending / active / user_removed / revoked |
subscription_source | Data | the URL last written into Nextcloud; the delete+recreate trigger is != desired |
last_seen_nc_at | Datetime | when the Nextcloud end was last observed to exist |
last_converged_at | Datetime | |
attempts, last_error | Int, Small Text | the medusa/keycloak shape |
No token column. The token is derived (§5.3), so storing it would create a
second copy that can drift and a secret to protect for no gain. This also
sidesteps the __Auth trap the estate has already been bitten by: a frappe
Password field lives Fernet-encrypted in __Auth, and an undecryptable one
reads as absent: a feed that 401s for a user whose row looks perfect.
5.7 The mapping: frappe Event → VEVENT
Section titled “5.7 The mapping: frappe Event → VEVENT”| ICS | frappe | notes |
|---|---|---|
UID | <Event.name>@<site> | stable across edits; the site suffix keeps two benches from colliding in one client |
SUMMARY | subject | |
DESCRIPTION | description | HTML stripped to text; ICS has no HTML body |
DTSTART / DTEND | starts_on / ends_on | converted to UTC, emitted with Z |
| all-day | all_day | VALUE=DATE, DTEND exclusive (the classic off-by-one) |
RRULE | repeat_this_event, repeat_on, repeat_till, weekday flags | Daily/Weekly/Monthly/Yearly → FREQ=; weekday flags → BYDAY |
STATUS | status / event_type == "Cancelled" | CANCELLED rather than omission, so a client that cached it clears it |
LOCATION | first non-empty of the location-ish fields | VERIFY the field name on v15 |
SEQUENCE | monotonic from modified | |
LAST-MODIFIED, DTSTAMP | modified, now |
Timezones: convert to UTC and emit Z. Frappe stores naive datetimes in
the site’s System Settings.time_zone. Emitting a VTIMEZONE block is more
faithful and much easier to get subtly wrong; UTC is unambiguous and every
client renders it in the viewer’s zone. A site whose time_zone is unset must
make the feed refuse (500 with a named cause) rather than silently assume
UTC and shift every meeting.
VERIFY the exact v15 field names above against frappe/desk/doctype/event/.
No frappe source tree was available while writing this; the field set is from
working knowledge of the v15 Event doctype and must be confirmed before code.
Explicitly out of scope for v1, and named so nobody has to re-derive
whether they were forgotten: HRMS Leave Application and Holiday List,
Project/Task deadlines, Appointment, and any doctype-to-calendar mapping that
is not the Event doctype. Each is a separate feed at most, never a widening
of this one.
5.8 Whose events are in whose feed
Section titled “5.8 Whose events are in whose feed”The feed for user X contains events where X is the owner, or X is
named in event_participants. Public events (event_type == "Public") are
included only when vars.nextcloud.includePublic is true, default false;
an estate that books every company holiday as a Public Event would otherwise
push it into every personal calendar without anyone deciding to.
The app MUST derive that set with an explicit query it owns, not by calling a
desk helper under frappe.set_user(). A permission-derived answer inside a
guest request is one refactor upstream away from either leaking or emptying,
and the rule above is three lines of SQL that a test can pin.
6. The convergence loop
Section titled “6. The convergence loop”6.1 Both-ends-exist, expressed as one GET
Section titled “6.1 Both-ends-exist, expressed as one GET”Doctrine: converge only when both ends exist. The naive reading needs two lookups, “does the Nextcloud user exist” and “does the ERPNext user exist”, and the second one is what would force an enumeration endpoint, a credential, or both.
It collapses to one request. The provider-side job already enumerates
Nextcloud users with occ (that end is free, it is running inside Nextcloud),
computes the candidate feed URL from the email and the shared secret (§5.3),
and then GETs the URL it is about to subscribe them to. A 200 proves the
ERPNext end exists, proves the token verifies, proves the network path works,
and proves the document parses, before any subscription is created. A 404
proves the far end has no such user.
The property that buys: this design cannot create a dead subscription. The recurring failure this catalogue keeps finding, a write that succeeds against coordinates that were never reachable, is structurally unavailable here, because the reachability check is the precondition.
6.2 States and transitions
Section titled “6.2 States and transitions” (no NC user with this email) ┌── absent ────────────────────────────────────────┐ │ │ │ NC user appears feed GET 200 │ └──▶ pending ──────────────────────────▶ active ───┤ ▲ │ │ │ NC user deleted │ │ ERPNext user │ (subscription died with them) │ │ disabled/deleted │ ▼ ▼ └─────────────────────────── user_removed / revokedpending: a Nextcloud user exists, the ERPNext side does not (404) or frappe was unreachable. Nothing is written. Re-evaluated every pass.active: the subscription exists and itssourceequals the desired URL.user_removed: the subscription was there last pass and is gone now (§6.4).revoked: the ERPNext user is gone or disabled; the subscription was deleted by the bridge.
6.3 The two asymmetric cases
Section titled “6.3 The two asymmetric cases”An ERPNext user with no Nextcloud account. Nothing happens, and nothing is recorded on the Nextcloud side, because the loop enumerates from Nextcloud. The user simply has a feed nobody fetches. That is the correct behavior: the bridge does not create Nextcloud accounts. (Account creation is the identity-broker’s job, and it is a different document.)
A Nextcloud user who appears later. Picked up by the next pass: the next
shc update in phase 1, the next hourly sweep in phase 2. No event, no
callback, no ordering requirement between the two stacks’ installs. This is the
level-triggered property earning its keep: there is no “the user was created
during the window” bug because there is no window.
6.4 Deletion, in every direction
Section titled “6.4 Deletion, in every direction”| what was deleted | what happens | who does it |
|---|---|---|
| an Event | it is absent from the next feed render | nobody; this is the subscription model’s whole payoff |
| an ERPNext user (or disabled) | the feed 404s; the bridge deletes the subscription and marks revoked | provider-side job |
| a Nextcloud user | the subscription dies with the account (Nextcloud cascades); the row returns to pending so a re-created account re-converges | Nextcloud, then the loop |
| the subscription, by the user, in the Nextcloud UI | RULING OWED; see below | undecided |
the edge (-i nextcloud! or uninstall) | every subscription whose source starts with this edge’s feed base is swept | socket unintegration job |
| the feed secret (deliberate rotation) | every URL changes ⇒ create-then-delete for every user, one pass | provider-side job, loudly |
★ RULING OWED: what happens when the user deletes the subscription
themselves. The two answers are both defensible and they are opposite:
- Respect it (recommended). Detect “present last pass, absent now”, record
user_removed, and stop re-creating. A bridge that re-creates a calendar the user deleted is a bridge the user cannot escape, and the subscription is an object the user owns, unlike huly-nextcloud’s Pattern A, where the user can only unshare a view of a collection the service account owns, which is why that bridge re-converges without qualm. - Re-create it, because the flagship bar is zero-touch and an admin-decided calendar is not the user’s to decline.
The recommendation is respect, with the removal reported rather than
silently absorbed, and no --var to override it (a knob here just moves the
ruling to whoever types the install command). This is stated as a ruling owed
rather than decided because it is the one edge in this design where the
software’s answer decides whether a user has a way out.
Detecting it needs the ledger, which is why it is a phase-2 behavior. In phase 1 a deleted subscription is re-created on the next update, and §9.1 says so in the operator-facing text rather than pretending otherwise.
6.5 Surviving the delete + recreate constraint
Section titled “6.5 Surviving the delete + recreate constraint”Rules that follow from §3.1, all of which the implementation must hold:
- Create the new, read it back, then delete the old. Never the reverse.
- Match the old by
sourceprefix, and delete byuri. The display name is human-facing (“ERPNext”), stays stable and unprefixed, and is part of no identifier anywhere; measured: create dedupes on the source URL, and delete takes theurifromdav:list-subscriptions’ first column. The URL origin is the edge’s identity handle, exactly as the GitLab socket uses a token-name prefix. - Nothing in the URL may derive from anything that moves. Not the stack
name, not a container alias that a second consumer could shadow (§4.4), not
an app version, not a date.
vars.nextcloud.feedBaseUrlis stated once by the operator or defaulted to the pinned short alias, and changing it is understood to rebuild every subscription in the estate. - The secret is never rotated on a schedule.
?autogenmints once. A deliberate rotation is a fleet-wide rebuild and must announce itself in the job log as one.
7. The refresh rate: what to set, and who is allowed to set it
Section titled “7. The refresh rate: what to set, and who is allowed to set it”The value is PT15M. The writer is the OPERATOR, not this integration.
Those are two decisions and the second one reverses an earlier draft of this section, so the reasoning for each is separate.
7.1 The value
Section titled “7.1 The value”The reasoning, in the two directions that matter:
- Down from the
P1Dcode default, because a day-old work calendar is not a calendar. The unset default is what makes this knob mandatory rather than optional. - Not
PT5M, even thoughPT5Mis what the probe proved. The cost is not the HTTP request (one conditional GET per user per interval against frappe’s own web workers, answered with a 304 in the steady state, negligible at any plausible headcount). The cost is that this knob is instance-wide (§3.2): every subscription any user ever added gets the same interval.PT15Mis fast enough that an event booked in a meeting shows up before the meeting ends, and slow enough to be defensible as a new floor for feeds the bridge does not own.
7.2 The writer, and why not the integration
Section titled “7.2 The writer, and why not the integration”An earlier draft had the socket write the knob under a composition rule (write
if unset, write if the stored value is longer, never lengthen someone else’s
tighter value). That is the wrong posture, and the socket-growth work in
flight (§0) states the reason better than the rule answers it: the knob is
instance-global, so an edge-clocked write lets the last consumer to bind
retune every other consumer’s feeds. The never-lengthen rule stops the worst
case, and it still leaves a subscription somebody else created being fetched
four times an hour because an ERP was installed. Provider-global configuration
is not a consumer’s to converge, the same boundary
docs/proposals/2026-08-07-config-vs-state-migration.md draws elsewhere.
So the posture is detection, never reconciliation, which is exactly what
the frappe package already does for the three facts it can observe and must
not repair (auth-secret-audit, login-path-audit, version-drift: all
detection only, all loud, all changing nothing):
-
the socket publishes the effective value it read back (
calendarRefreshRate, empty meaning “unset, soP1D”); -
the bridge’s job compares it against
vars.nextcloud.refreshRate(defaultPT15M, the value it wants); -
if the instance is slower, the job says so, with the command, and subscribes anyway:
nextcloud calendar: this instance refreshes webcal subscriptions every P1D(dav.calendarSubscriptionRefreshRate is unset, so the code default applies).ERPNext events will take up to a day to appear. Set it once, as operator:occ config:app:set dav calendarSubscriptionRefreshRate --value=PT15MIt is INSTANCE-WIDE; it also retunes every subscription your users addedthemselves. This integration will not write it for you.
Never blocking on it is deliberate: a calendar that is a day behind is worth more than an install that refused, and the operator now has the one line that fixes it.
★ The knob is necessary and not sufficient, and this is the largest
unverified dependency in the document. RefreshWebcalJob is a background
job. Nextcloud only runs background jobs when a runner runs them, and
apps/collaboration/nextcloud/ sets no backgroundjobs_mode, ships no cron
container, and runs no cron.php; grep confirms it: the package has no such
line anywhere. The official image does not run cron on its own. If the
instance is in AJAX mode, background jobs execute one-per-page-load, so an idle
Nextcloud refreshes nothing and the refresh rate is a floor that is never
reached.
The probe proved the mechanism end to end, which does not establish that it fires unattended on an SHC-packaged Nextcloud. Settle it with one command:
occ config:system:get backgroundjobs_mode # expect: cronocc background-job:list --limit 5 # expect RefreshWebcalJob rows advancingand if the answer is ajax, the fix is a small, separately shippable piece
of work on the Nextcloud package: a crons: entry running php -f /var/www/html/cron.php as www-data every 5 minutes, plus occ background:cron. Note the caveat apps/communication/matrix/app.yaml records
for the first cron user in the catalogue: crons: only fires under a daemon,
and on a CLI-thin install the row is never written and nothing warns.
This is a prerequisite of the bridge, not a part of it, and it benefits every other background job on the instance (notifications, previews, trash expiry, federated shares).
And note what the socket’s calendarRefreshRate read-back does not settle:
it reports the configured interval, which says nothing about whether any
runner is executing the jobs that honor it. A PT15M on an instance in AJAX
mode is a number, not a cadence.
8. The exact SHC surfaces
Section titled “8. The exact SHC surfaces”8.1 apps/platform/frappe/nextcloud.plug.yaml: new
Section titled “8.1 apps/platform/frappe/nextcloud.plug.yaml: new”Frappe consumes the nextcloud socket. Not caldav, not calendar: the
socket already exists, it is a singleton named for the app (its own header
states why), and this is an additive consumer of it.
required: false # a calendar must never block an ERP install
services: - frappe-web # Nextcloud dials IN to this service; the attach is # what publishes the alias §4.4 depends on # (the sweep handle is the feed URL, not a label)
data: # ★ NO `label`. On this socket the label is the OPT-IN to the admin grant: # declaring one mints a Nextcloud app password on the admin account, which # carries the admin's full authority (no scopes exist). Phase 1 writes # everything through occ inside the provider and holds NO Nextcloud # credential, so asking for one would be taking the estate's most # privileged secret to not use it. Phase 2 rung A adds the label on the day # something consumer-side actually reads /cloud/users; see §9.2. siteName: "{{ vars.siteName }}" # the identity check of §4.4 feedBaseUrl: "{{ vars.nextcloud.feedBaseUrl | default('http://frappe-web:8000') }}" feedSecret: "{{ vars.nextcloud.feedSecret }}" # @secret calendarName: "{{ vars.nextcloud.calendarName | default('ERPNext') }}" calendarColor: "{{ vars.nextcloud.calendarColor | default('') }}" refreshRate: "{{ vars.nextcloud.refreshRate | default('PT15M') }}" includePublic: "{{ vars.nextcloud.includePublic | default(false) }}" matchDomains: "{{ vars.nextcloud.matchDomains | default('') }}"⚠ {{ stack }} in a plug data: render is the PROVIDER’s stack, not this
one (sonarqube/gitlab.plug.yaml documents the trap; ce builds plugCtx with
"stack": sp.ProviderStackName). That is why feedBaseUrl defaults to a literal
short alias instead of a derived tenant FQDN, and, when phase 2 adds a
label, why it must be built from tenant (which is the consumer’s) and
never from stack, which would silently name the Nextcloud.
The identity check siteName exists for: the provider-side job GETs the
feed and compares a X-SHC-Bridge-Site response header against
integration.plug.data.siteName. A mismatch means the short alias resolved to
a different bench (§4.4) and the job refuses the whole edge rather than
subscribing users to a stranger’s calendar. This costs one header and removes
an entire class of silent cross-tenant leak.
Also on this file: jobs.post_deployment with the consumer-side activation
job (§8.3), and jobs.unintegration that sets the bridge’s mode to off on
disconnect. Not bench uninstall-app; removing an app from a live site is
the destructive half of the 2026-08-05 outage class, and a disabled bridge
serving 404s is the correct terminal state.
8.2 apps/platform/frappe/vars.yaml: additions
Section titled “8.2 apps/platform/frappe/vars.yaml: additions”nextcloud: feedBaseUrl: "" # empty → the short alias; set to a public # https origin when more than one bench binds # one Nextcloud, or when the estate would # rather not enable allow_local_remote_servers feedSecret: "ref+vault://calendar_feed_secret?autogen" calendarName: "ERPNext" calendarColor: "" refreshRate: "PT15M" includePublic: false matchDomains: "" # comma-separated; empty = every domainwith the matching vars: type declarations in app.yaml
(feedSecret@secret, the rest @string/@boolean), each carrying the
constraint that governs it; feedBaseUrl in particular must say that changing
it rebuilds every subscription (§3.1).
8.3 The consumer-side job: activation and settings
Section titled “8.3 The consumer-side job: activation and settings”frappe-configure-nextcloud-calendar, a post_deployment job on the plug,
context: service, service: frappe-web. It mirrors
frappe-configure-keycloak-connector line for line, because that job already
solved this exact problem for frappe_keycloak:
-
Refuse if the app is not on the bench, naming the image requirement, in the IMAGE-OWNED language the bats guard pins, never suggesting a vdeployment, never running
bench get-app:Terminal window if ! ./env/bin/python -c "import frappe_nextcloud" 2>/dev/null; thenecho "the nextcloud calendar bridge was requested but frappe_nextcloud is not on this bench." >&2echo "Plug mechanisms are IMAGE-OWNED (owner ruling 2026-08-08): baked in, activated" >&2echo "through vars, never installed as vdeployments. Point images.frappe at an image" >&2echo "that bakes frappe_nextcloud." >&2exit 1fi -
bench --site <s> install-app frappe_nextcloudwhen absent. Safe, per the corrected rule in the Dockerfile header: the code is already importable, so registration has no import window. -
bench --site <s> set-configthe settings the app reads:shc_nc_calendar_mode,shc_nc_calendar_feed_secret,shc_nc_calendar_include_public,shc_nc_calendar_site. Site config, not environment, for the reasonfrappe_medusa/sync/settings.pygives: the web worker, the scheduler and abench executemust all see one configuration, and only site config reaches all three. -
Read back and fail loudly:
bench --site <s> execute frappe_nextcloud.api.preflight, asserting the app answers, the secret it holds matches (compared as a digest, never echoed), and the endpoint is registered. House discipline: no write in this catalogue is trusted by its exit code.
Why activation lives here and not in vars.activateApps. activateApps
is the right home for an app every site should carry regardless of edges. This
one is meaningful only when a nextcloud edge exists; activating it estate-wide
would put a feed endpoint on benches that nothing subscribes to. Edge-scoped
activation, edge-scoped teardown.
8.4 apps/collaboration/nextcloud/nextcloud.socket.yaml: additive growth
Section titled “8.4 apps/collaboration/nextcloud/nextcloud.socket.yaml: additive growth”The socket reserved this from the start (“the admin capability grows HERE…
additive keys, never a second socket”), and the in-flight growth of §0 has
already taken the first half: the discovery keys, the label-gated admin grant,
and grant-nextcloud-admin in jobs.integration.
Phase 1 needs none of that. No new data: key, no credential, no label
(§8.1); every write is occ, inside the provider. What it adds:
schema.plug: the keys §8.1 sends (siteName, feedBaseUrl,
feedSecret@secret, calendarName, calendarColor, refreshRate,
includePublic, matchDomains), each described with its constraint, beside
the label the grant already declares.
A SECOND job in jobs.integration: nextcloud-subscribe-calendar-feeds,
after grant-nextcloud-admin, context: service, service: nextcloud,
user: www-data (occ refuses to run as root; www-data owns config.php on
this image). No timeout: field; the socket integration job struct has
none, so writing one parses and then vanishes; the waits carry their own
budgets. In order:
- No
feedBaseUrlor nofeedSecret→ exit 0, “nothing to converge”. - Probe the consumer once: GET
<feedBase>health. Unreachable → exit 0, deferred, printing the exact remedy (§9.1). Never fail the bind: a Nextcloud that refused to finish binding because an ERP was mid-boot would be a worse product than a calendar that arrives one update later. - If the feed host is in a private range:
occ config:system:set allow_local_remote_servers --value=true --type=boolean, and say what it widens; the flag is instance-wide and lets every Nextcloud feature that fetches a URL (federation, external storage, webcal) reach private addresses. Skip it entirely whenfeedBaseUrlis a public origin, and say that too, so an operator can see which posture they are in. occ user:list→ for each uid,occ user:info <uid> --output=json→ email. Skip users with no email; refuse (loudly, without writing) when two users share one email; applymatchDomainswhen set.VERIFYwhetheruser:list --infoemits emails in one call; the per-user loop is N execs and is the slow part of this job on a large instance.- Per candidate: compute the URL (§5.3), GET it, and branch on §5.2’s status
table. On 200, compare
X-SHC-Bridge-SitetositeName(§8.1) and refuse the edge on mismatch. - Converge, using the measured semantics of §0.4:
occ dav:create-subscription <uid> <name> <url> [color], and read “already exists for this user” (exit 1) as converged, not as a failure. Thenocc dav:list-subscriptions <uid>for any subscription under this edge’s feed-base prefix carrying a different source, andocc dav:delete-subscription <uid> <uri>it; create first, delete second (§6.5), and theuriis the first column of the list, never the name. - Compare the socket’s read-back
calendarRefreshRateagainstvars.nextcloud.refreshRateand report (§7.2). This job never writes that knob. - Print a one-line summary: created / converged / deferred / skipped counts. A convergence loop that cannot be read from its log is a convergence loop nobody trusts.
jobs.unintegration: nextcloud-sweep-calendar-feeds: for every user,
delete every subscription whose source starts with the frozen feedBaseUrl
from the edge state. Not lifetime: managed: this deletes a pointer the
integration itself created, not user-authored data, the same reasoning that
keeps GitLab’s token sweep ungated.
8.5 Why the bench app is not a vapp:
Section titled “8.5 Why the bench app is not a vapp:”Because the owner ruled it, and because the ruling has a body count.
Plug mechanisms are IMAGE-OWNED: baked and vars-activated, never vdeployments (owner ruling 2026-08-08).
Pinned three ways already, all of which this app inherits:
apps/platform/frappe/tests/tests.bats: “no frappe plug declares a vapp dependency; mechanisms are image-owned” fails if any*.plug.yamlin the package grows avapp:key.nextcloud.plug.yamlis inside that glob on the day it is created; no new guard is needed for the negative.- The same file asserts the OIDC plug’s refusal text says
IMAGE-OWNEDand never namesshc install frappe/plugin. frappe/docker/Dockerfile’s header records the 2026-08-05 outage: an app installed into a live preloaded gunicorn entered the site’s app list before the master’s cachedsys.pathcould see it, andhq.flyingfoxlabs.in500’d on every route until it was manually removed. The window is inherent to installing a Python app into a running preloaded gunicorn.
And a fourth reason specific to this bridge: the plug’s job refuses when the app is absent (§8.3). A vdeployment-delivered mechanism would make that refusal a race: bind before the vApp lands and the edge fails; bind after and it succeeds, which is precisely the class of ordering bug the bake rule deletes.
bridges/erpnext-keycloak/README.md still says it installs “through
shc/apps/frappe’s plugin VApp like any other bench app”. That README
predates the ruling. It is not a counter-example; it is a document owed an
update.
8.6 How the app gets baked
Section titled “8.6 How the app gets baked”frappe/docker/Dockerfile gains a second app, in the shape the first one
established, and that shape is not decoration:
ARG FRAPPE_NEXTCLOUD_REPO=https://gitlab.com/bitspur/frappe/nextcloud.gitARG FRAPPE_NEXTCLOUD_REF=<commit sha, never a branch>
RUN set -eux; \ git init --quiet apps/frappe_nextcloud; \ cd apps/frappe_nextcloud; \ git remote add origin "${FRAPPE_NEXTCLOUD_REPO}"; \ git fetch --quiet --depth 1 origin "${FRAPPE_NEXTCLOUD_REF}"; \ git checkout --quiet FETCH_HEAD; \ test "$(git rev-parse HEAD)" = "${FRAPPE_NEXTCLOUD_REF}"; \ cd /home/frappe/frappe-bench; \ ./env/bin/pip install --no-cache-dir -e apps/frappe_nextcloudEverything the existing file says applies unchanged and must be honored:
USER frappe,./env/bin/pipand never barepip; the outage’s second cause was an install that landed in system python while gunicorn ran from the bench venv.- A separate
RUNassertingimport frappe_nextcloudagainst./env/bin/python, in a fresh layer over the committed filesystem. - Nothing under
sites/orlogs/.tests/unit/ci/frappe_image_volume_writes_test.goenforces it, because Docker does not: under BuildKit a write to a VOLUME path persists into the published image and into a fresh named volume. - A commit sha, never a branch; two builds a week apart must not differ.
- The provenance manifest assertion picks the app up automatically
(
record-versions.shwalks the bench), andfrappe_nextcloudmust be added to the manifest’s required-app list besidefrappe,erpnextandfrappe_keycloak. images.frappeinvars.yamland thisFROM/app set are two halves of one decision;tests/unit/catalog/image_provenance_test.goreds if they drift.
★ And the trap that must be stated with the delivery, every time: the bench
volume is seeded once. On an existing bakeApps: false deployment, the
default, and what both live production benches run, .seeded already exists,
so the new app does not arrive and there is no error. version-drift
reports stale and names it, which is the only reason the no-op is visible.
Delivering the bridge to an existing vapp-mode bench needs a deliberate,
consented step (a reinstall with bakeApps: true, or the image-identity-keyed
re-seed that is still open). Bumping the pin is not that step and must not be
reported as one.
8.7 Guards to add
Section titled “8.7 Guards to add”| test | asserts |
|---|---|
apps/platform/frappe/tests/tests.bats | the new plug carries no vapp: (covered by the existing glob), the activation job says IMAGE-OWNED and never bench get-app, required: false, and services: pins frappe-web |
| same | the plug’s data: uses tenant and never stack (the provider-stack trap) |
apps/collaboration/nextcloud/tests/tests.bats | the integration job never fails on an unreachable consumer (an exit 0 deferral branch exists), the refresh-rate write is conditional, and the sweep keys on feedBaseUrl and not on the display name |
tests/unit/catalog/image_provenance_test.go | the Dockerfile app set and imageVersions agree (existing test, new row) |
| the app’s own repo | the write boundary: no code path writes anything into Nextcloud, and no code path emits an event body from a doc hook |
9. The phased plan
Section titled “9. The phased plan”9.1 Phase 1: deploy-time backfill. Buildable today.
Section titled “9.1 Phase 1: deploy-time backfill. Buildable today.”What ships: existing users get their ERPNext calendar in Nextcloud, and it stays correct forever. What is missing is only when new users are picked up.
Deliverables, in dependency order:
| # | Deliverable | Where | New component? |
|---|---|---|---|
| 1 | frappe_nextcloud with one endpoint (§5.2), the HMAC verifier (§5.3), the Event→VEVENT mapping (§5.7), the visibility rule (§5.8), and preflight | a new repo | the bench app; see below |
| 2 | The Dockerfile app + pin bump | frappe/docker/Dockerfile, apps/platform/frappe/vars.yaml | no |
| 3 | nextcloud.plug.yaml + vars + the activation job | apps/platform/frappe/ | no |
| 4 | schema.plug + jobs.integration + jobs.unintegration | apps/collaboration/nextcloud/nextcloud.socket.yaml | no |
| 5 | The guards | both tests.bats | no |
| 6 | The background-job prerequisite (§7) | apps/collaboration/nextcloud/ | a crons: entry, if the mode check says ajax |
★ “No new component” is true of the SHC side and only the SHC side. There is no broker, no sidecar, no vApp, no daemon, no new socket and no new credential; items 2–6 are edits to files that already exist, using idioms that already exist in the same files. The bench app is genuinely new code, and there is no version of this feature without it: nothing in frappe core serves ICS. What phase 1 buys is that the app is one read-only endpoint plus a hash comparison: no ledger, no scheduler, no queue, no state, no Nextcloud credential, and no doctype. That is the smallest bench app in the estate, and it is exactly the part that phase 2 keeps unchanged.
How it converges, and the one rough edge. The backfill runs in the socket’s
integration phase, which fires on every consumer install and every
update (§4.3). On a fresh install frappe is not up yet, so the job defers,
and must say so in words an operator can act on:
nextcloud calendar: frappe is not reachable at http://frappe-web:8000 yet. On a first install this is expected; the consumer's containers start after this phase. No subscription was created and nothing was changed. Converge with: shc update <frappe-stack> -i nextcloud=<nc-stack>Every later shc update of the frappe stack re-runs it and converges. So the
operator’s clock is the update, which is honest for a deploy-clocked mechanism
and is exactly what phase 2 replaces.
Acceptance for phase 1 (each line is a command, not a feeling):
occ dav:list-subscriptions <uid>shows one subscription per matched user, with the expected source.curl -sS -o /dev/null -w '%{http_code}' "<feed url>"→200; the same URL with a mangled token →401; with an unknown user →404.- A second
shc updatecreates nothing and reports “converged” for every user, the idempotency assertion, and the one most worth automating. - With the knob unset, the job’s log carries the
P1Dwarning and its remedy line (§7.2) and still subscribes; after the operator runs the command,occ config:app:get dav calendarSubscriptionRefreshRate→PT15Mand the next run’s log is quiet. - An event created in ERPNext appears in the Nextcloud calendar within one refresh interval, which is where §7’s background-job check gets settled for real.
shc update <frappe-stack> -i nextcloud!leaves zero subscriptions carrying the feed base.
9.2 Phase 2: the runtime loop
Section titled “9.2 Phase 2: the runtime loop”What it adds: the ledger (§5.6), the User doc events and the hourly sweep
(§5.4), the user_removed detection (§6.4), and per-user revocation via
generation (§5.3). New users are picked up in minutes with no operator
action.
STATUS 2026-08-10: built to the line the owed rulings draw. Landed in
frappe_nextcloud0.2.0 (commit8b3ee4d): the ledger doctype (rows are UNLINKED on user deletion, never deleted; a deleted row would reset the generation and re-arm every revoked URL;on_trashruns before frappe’s link check, which is what lets the User be deleted at all), theUserdoc events andhourly_longsweep funnelling into one level-triggered reconcile, per-user revocation (bench nextcloud-revoke-feed --user <a>), and a preflight that asserts the ledger table and the scheduler pulse (§5.4’s VERIFY). The wire growth this forced, which §5.3 left implicit: the provider-side job derives every candidate at generation 1 with no ledger to consult, so a bumped user’s feed answers that probe410withX-SHC-Feed-Generation: <current>, distinct from401(which stays the refuse-the-edge secret-mismatch verdict) and disclosed only to a caller presenting a token that once verified; the socket job re-derives at the announced generation and the revocation lands as the delete + recreate of §3.1, scoped to one user. Generation 1 stays classifiable as stale at any distance (bounded window otherwise) or the job would read its own bootstrap as a mismatch. NOT built, still owed: the effector rung below (so new-user pickup remains update-clocked, not minutes), the observation surface, anduser_removeddetection; the recommended respect reading is honored passively (nothing flips auser_removedrow back topending), but nothing SETS the state, because detection needs an observer and the ruling is not this code’s to make.
The open question is the effector, and it is genuinely open: the bench app
runs consumer-side and occ is provider-side (§3.3). Three rungs, ranked, with
what each costs:
| Rung | How the loop writes | Cost | Doctrine fit |
|---|---|---|---|
| A. One-capability helper on the Nextcloud side | a route wrapping createSubscription, admin-authed with a per-consumer app password the socket mints (gitlab shape) | the credential half is already built (§0): declare a label and the grant arrives. What remains is a bespoke Nextcloud app with no store release, so it must itself be image-owned: an SHC-built Nextcloud image, which the estate does not have. And the grant is admin-equivalent; Nextcloud exposes no scoped admin token, and occ no --scope. | clean: consumer-side loop, provider publishes one generic capability, never pair logic |
| B. Login-time convergence | at the user’s next SSO login, frappe exchanges their token for a Nextcloud-audience one and the user’s own client creates the subscription over CalDAV MKCOL | needs the Keycloak audience mapper and bearer-CalDAV probes, still open, and shared with the picker. A user who never logs into ERPNext never gets a calendar, and deletions wait for a login. | clean, and it needs zero stored credentials, the strongest property on the table |
| C. Provider-side cron pulling the consumer’s desired set | a crons: job on the Nextcloud stack calling a frappe enumeration endpoint | cheapest to build, but blocked on §4.5 (a cron sees no integrations), so the edge’s parameters must be persisted somewhere the cron can read | violates placement: an edge-broker living provider-side is what doctrine reserves for the identity-broker alone |
Recommendation: B if its probes go green, A otherwise, never C. B is the
only rung that needs no credential at all, and its weakness (a user who never
logs in) is bounded by the fact that phase 1 already covers everyone at every
update. RULING OWED on the rung, and it is not urgent: phase 1 ships without
choosing.
★ Worth recording that the socket-growth work (§0) enumerated the same three paths, in the same order, independently, per-user bearer via token exchange, a provider-side occ job for backfill, a helper endpoint in a Nextcloud app, and reached the same conclusion, that until one is proven the socket grants observation only. Two designs converging on one taxonomy is the strongest evidence available that the taxonomy is the real one.
Observation, in phase 2, comes from the grant rather than from occ: the
consumer-side loop reads <ocsUrl>/cloud/users/details with the minted app
password (OCS-APIRequest: true on every call) instead of enumerating from
inside the provider. That is what makes the loop consumer-side at all, and it
is the moment the frappe plug declares its label (§8.1).
Note the ordering trap phase 2 inherits from §4.2: any consumer-side job
that reads a minted Nextcloud credential must be a post_install/post_update
hook job, not a plug post_deployment job. Rung A walks into this on day one.
9.3 Out of scope for both phases
Section titled “9.3 Out of scope for both phases”Nextcloud → ERPNext writes of any kind. Contacts (the org address book is huly-nextcloud’s Pattern A and a different mirror). Free/busy and scheduling. Per-user calendar creation in Nextcloud. HRMS leave, holidays, project deadlines (§5.7). Multi-site benches serving one feed per site to one Nextcloud user; one bench, one feed, per user.
10. Remaining unknowns, each with the command that settles it
Section titled “10. Remaining unknowns, each with the command that settles it”Ranked by what they would cost if the assumption is wrong.
| # | Unknown | Settles with | If wrong |
|---|---|---|---|
| 1 | Does the Nextcloud instance run background jobs unattended? (§7) | occ config:system:get backgroundjobs_mode | the whole feature appears to work and refreshes approximately never; fix is a crons: entry on the Nextcloud package |
| 2 | Do frappe guest-whitelisted methods let a handler set an arbitrary HTTP status? (§5.2) | one endpoint, curl -w '%{http_code}' | the both-ends-exist test of §6.1 collapses; a missing user would read as 200 and everyone gets subscribed |
| 3 | The frappe v15 Event field names and recurrence flags (§5.7) | read apps/frappe/frappe/desk/doctype/event/event.json on the pinned image | the mapping is wrong in detail, not in shape; no source tree was available while writing this |
| 4 | Does a crons:-run job see an integrations namespace? (§4.5) | read execute_job_task’s render context in ce | changes only which rungs are available in phase 2 |
| 5 | Does occ user:list --info emit emails in one call? (§8.4) | occ user:list --info --output=json | the backfill is N execs on a large instance, slow, not wrong |
| 6 | Does Nextcloud honor userinfo credentials in a subscription source URL? | subscribe to https://u:p@host/... and watch the fetch | irrelevant if it does; the token design does not need it and should not adopt it |
Settled while this was being written, by the socket-growth work of §0, and
recorded here because an earlier draft carried both as open: the source URL is
what dav:create-subscription dedupes on (and it exits 1 rather than no-op),
and dav:delete-subscription <uid> <uri> takes the uri from
dav:list-subscriptions’ first column. The display name is part of no
identifier.
★ And the largest one, stated without hedging: the bench app does not exist. Not a stub, not a branch, not a scaffold. Every “the app MUST…” above is a specification written before the code, and the first implementation pass will find things this document got wrong. The two probes settle the platform questions, which is what unblocked the design, and settle nothing about the app.
11. Rulings owed
Section titled “11. Rulings owed”- The user deletes their subscription (§6.4): respect it (recommended) or re-create it. This decides whether a user has a way out of a bridge an admin turned on.
- The phase-2 effector rung (§9.2): A, B, or a refusal to build phase 2 at all until a second consumer needs the same capability. Not urgent; phase 1 ships without it.
allow_local_remote_serversas a default (§8.4): the job can enable it silently when the feed is in-fabric, or refuse and require an explicit--varacknowledging that it widens what every Nextcloud fetcher can reach. The recommendation is enable and say so loudly, because the alternative posture, give frappe a public origin, is the better answer and should be the documented one.
Not owed, because it is decided: who writes
dav.calendarSubscriptionRefreshRate. The operator does; the integration
detects and reports (§7.2). An earlier draft of this document had the socket
write it under a composition rule, and that draft was wrong.