refactor/introduce IContext

[max-nextcloud]

• chore(refactor): Introduce IContext and FileContext
• chore(refactor): simplify IContext API with helper classes

Todo

Prerequisits

• chore(upgrade) nextcloud/ocp and fix deprecation #9153
• fix/no conflicts on sync #9149

Backend

• Handle sync requests with IContext.
• get text file in AttachmentService based on context.
• Fix unit tests for ApiService.
• Fix 412 resonses to push requests.
• handle saving in IContext.
• Address refactor/file service #9028 (comment)
• Address refactor/file service #9028 (comment)
• check for other requests that rely on the context.
• Migrate existing documents.
• Add index for context_type, context_id.
• Have a lazy context that does not setup the filesystem unless needed.
• always create the context on the same layer.

Frontend

• Add context arguments to createCollaborativeEditor.
• Pass these arguments to the CollaborativeEditor component as props.
• Use these props to connect.
• Provide these props when saving. We still use the documentId to save and resolve the context on the backend.
• Look into attachment handling / attachment resolver - in particular with non-file context

Testing

• Test with public file shares
• Check playwright tests
• Fix playwright
  • print test since 5cca04c shows the placeholder at the bottom
• Fix cypress tests
• Test with collectives

Feedback

• Separate classes
• specify strict types on new classes
• double check: a call to removeInactiveSessionsWithoutSteps() within the create flow was removed, and not introduced back elsewhere.
• consider to mark the new event unstable or experimental (not aware of a phpdoc or internal established annotation. )

Documentation

• document how to implement and register a Context

[blizzz]

So far I read up to commit chore(tweak): return first editable file early. I love your iterative style and the discipline you keep with having small, digestible and sensible commits! My impression is also that with having the abstraction layers, there are many places where it just gets cleaner, and having specific logic better capsuled!

What I stumble over is that the IContext file contains the additional classes DocumentData, SessionInfo, NewSessionData. Usually this is something we keep separate and I am not sure it will always works with autoloading? Also about fellow developer expectations. Maybe something to consider.

Maybe this is also OK, just to double check: a call to removeInactiveSessionsWithoutSteps() within the create flow was removed, and not introduced back elsewhere. Alright if intentional of course.

No biggie: new classes miss the declare(strict_types=1); statement.

Can consider to mark the new event unstable or experimental, though I am not aware of a phpdoc or internal established annotation.

[blizzz]

On my dev instance I get an error during Migration:

{
  "reqId": "miQrQfvExjkhgL8Z3V6T",
  "level": 3,
  "time": "2026-08-19T14:14:45+00:00",
  "remoteAddr": "",
  "user": "--",
  "app": "updater",
  "method": "",
  "url": "--",
  "scriptName": "occ",
  "message": "\\OC\\Updater::failure: Exception: Database error when running migration 090000Date20260817110024 for app text\nAn exception occurred while executing a query: SQLSTATE[23502]: Not null violation: 7 ERROR:  column \"context_type\" of relation \"oc_text_documents\" contains null values",
  "userAgent": "--",
  "version": "35.0.0.3",
  "occ_command": [
    "occ",
    "upgrade"
  ],
  "data": {
    "app": "updater"
  }
}

DB is postgres.

Probably happens because the column is added as NOT NULL but the rows would be empty (=> NULL). Maybe set the default to "file"?

UPDATE: same with context_id. Default to 0?

[blizzz]

TIL Private elements.

[blizzz]

wonder whether it makes sense to have an umbrella interface here to use as return type hint. Or a wrapper class. Probably overkill. Benefit would be not to have a union return, but at some point you've got to figure out when to work with a share or user at the callee, so… just thinking loudly.

[blizzz]

$document and $updatedDocument are they same. Objects are passed by reference, and FileContext does not clone $document but just returns it (provided the checks pass and don't return null)

[blizzz]

here as well, same document instance that is acted upon

[blizzz]

It needs to be registered yet

[blizzz]

debug leftover?

[blizzz]

could also result in a DoesNotExistException, which is not handled

[blizzz]

Suggested change

	$factoryClassName = $this->getContexts()[$type];
	$factoryClassName = $this->getContexts()[$type] ?? null;

to avoid log spam on non-existing keys

[blizzz]

is now context type + id, innit?

[blizzz]

I get the hint:

ViewerComponent.vue migrated to type-only defineProps without withDefaults, making active and isEmbedded required and dropping the onLoadedHandler: () => {} default; Viewer mounts this externally via ViewerView.js (props: ViewerComponent.props), so expect missing-required-prop warnings and @loaded="undefined". And createEditor.ts still gates on Boolean(options.fileId), so a caller using the newly-advertised context option falls through to createMarkdownContentEditor.

But I do not fully understand it 🙈

[blizzz]

The optional query type is not specified, at least for context_id it should be IQueryBuilder::PARAM_INT. IQueryBuilder::PARAM_STR is the default.

[blizzz]

actually, I am not sure whether this is safe, also across DB types. I do not see similar code in Nextcloud. Maybe double check with @nickvergessen

[nickvergessen]

Adding autoincrement does not work as far as I recall. Had it in another app when we had to add the primary keys to all databases.