Groupware by pbleser-oc · Pull Request #1994 · opencloud-eu/opencloud

pbleser-oc · 2025-12-09T08:30:50Z

Description

Ongoing implementation of the Groupware backend service, which initially happened on its own branch but should now occur on the main branch.

Changes are almost exclusively on packages that are distinct to the Groupware backend, namely

pkg/jmap, pkg/jscalendar and pkg/jscontact: contain the implementation of the JMAP protocol and data models for Core, Mail, Contacts, Calendars, Blobs, ...
services/groupware: contains the Groupware backend service which is currently configured to not be started by default, and must be explicitly included in the START_ADDITIONAL_SERVICES property

Changes to common areas include:

devtools/deployments/opencloud_full: addition of a container of the Stalwart mail server which is used for Groupware functionality
pkg/structs: add more helper functions that are then used in pkg/jmap and services/groupware

Note that it is not fully functional yet and is going to be under continued and ongoing development along with its UI counterparts.

Specifically, the following aspects are lacking and only implemented in a skeletal way as a proof of concept:

API documentation: originally developed using go-swagger and redocly-cli, but which is having severe limitations and might be superseded by an ongoing implementation of a custom source code parser which renders OpenAPI
unit tests: very little coverage if at all, which is mostly due to most of the implementation of the Groupware backend doing relatively little logic and is mostly implementing the JMAP model
integration tests: some coverage exists that performs tests against a Stalwart container using testcontainers, but will be made more exhaustive
k6 black box tests: none implemented yet
system documentation: none implemented yet, too early to do so

The Groupware backend is not meant to be used productively yet.

services/auth-api/pkg/service/http/v0/service.go

services/groupware/DEVELOPER.md

butonic · 2025-12-10T16:06:38Z

services/groupware/DEVELOPER.md

+curl -ks -D- -X POST \
+"https://keycloak.opencloud.test/realms/openCloud/protocol/openid-connect/token" \
+-d username=alan -d password=demo -d grant_type=password \
+-d client_id=groupware -d scope=openid


when working from top to bottom this fails. using a client_id=web works ... so I need to add a client id for the goupware somewhere ...

I did add a JSON file devtools/deployments/opencloud_full/config/keycloak/clients/groupware.json, expecting it to be automatically picked up, but that might require re-creating the Keycloak container... ?
In any case, that was a beginner's mistake, there is really no reason to have a distinct client ID for the groupware, as the Web UI is going to use web instead.

Removed that config file and updated the documentation accordingly to use web instead, in cfbbe02

butonic · 2025-12-10T16:08:15Z

services/groupware/DEVELOPER.md

+to which one should receive the following response:
+
+```java
+A OK [CAPABILITY IMAP4rev2 ...] Authentication successful


hm, I need to dig into:

stalwart-1 | 2025-12-10T16:07:05Z TRACE Raw IMAP input received (imap.raw-input) listenerId = "imaptls", localPort = 993, remoteIp = 172.39.0.1, remotePort = 45034, size = 19, contents = "A LOGIN alan demo\r\n" stalwart-1 | 2025-12-10T16:07:05Z ERROR LDAP error (store.ldap-error) listenerId = "imaptls", localPort = 993, remoteIp = 172.39.0.1, remotePort = 45034, reason = "I/O error: Connection refused (os error 111)", causedBy = "crates/directory/src/core/dispatch.rs:25", id = "A"

devtools/deployments/opencloud_full/.env

services/groupware/DEVELOPER.md

services/groupware/pkg/groupware/api.go

butonic · 2025-12-11T13:53:56Z

pkg/jmap/api.go

@@ -0,0 +1,49 @@
+package jmap


I think we should drop the jmap_ prefix from all files in this package

butonic · 2025-12-11T14:46:38Z

devtools/deployments/opencloud_full/opencloud.yml

+      AUTH_BASIC_LDAP_BIND_PASSWORD: "admin"
+      USERS_LDAP_BIND_PASSWORD: "admin"
+      GROUPS_LDAP_BIND_PASSWORD: "admin"
+      IDM_LDAPS_ADDR: 0.0.0.0:9235


I configured everything on .compose.test to prevent collisions with my .opencloud.test deployment. The stalwart URL then needs to be set for the groupware:

Suggested change

IDM_LDAPS_ADDR: 0.0.0.0:9235

IDM_LDAPS_ADDR: 0.0.0.0:9235

GROUPWARE_JMAP_BASE_URL: https://${STALWART_DOMAIN:-stalwart.opencloud.test}

oh and we need to set FRONTEND_GROUPWARE_ENABLED: "true" and enable the mail app in the web config when stalwart is enabled ... but that connot be configured with a simple env var ... 😞 we need to replace the config file then ...

butonic

Ok, I still don't have a menu entry for mail in the web UI even though the config.json contains the mail app. I assume that is a problem with my setup/config. in any case, I can see the mail UI when navigation to {$OC_URL}/mail manually. \o/

I did run into some minor issues when following the docs. If you could address them ~~(and enlighten me on how to get menu to show the groupware apps)~~ I'm happy to merge this. I mostly want others to be able follow the DEVELOPMENT.md and have a working setup. Kudos for that, btw.

The groupware service itself follows our ... boilerplate ... service code ... and implements the JMAP handling. I assume that will have to evolve, but we can merge it and iterate.

Tip

the web repo has a compose file with all the apps enabled. That gave me the final hint to get the menu entries

…enLDAP container as a directory for user authentication

…15.5

… 0.15.5

- fix a bunch of minor issues and typos that were found using GoLand and gosec - add a gosec Makefile target for Groupware related files, in services/groupware/Makefile - enable checking JMAP session capabilities for events and contacts, and only enable skipping that check for tasks until those are implemented in Stalwart as well - fix a CWE-190 (integer overflow or wraparound) found by gosec - consistently use struct references for methods of Groupware and Request, instead of mixing up references and copies - always log errors when unable to register a Prometheus metric

…g (must use updated instead of name)

* implement ContactCard retrieval endpoint for syncing * re-implement that endpoint for Email too * fix the Mailbox changes endpoint to actually return changes about Mailboxes, and not about Emails * when querying the diff of Mailboxes without any prior state, return an error since the result is not what one would expect * introduce the 'changes' API tag and group * refactor the successful response functions to consistently return an object type and object state whenever possible * move the syncing endpoints under /accounts/*/changes/ for better clarity, e.g. /changes/emails instead of /emails/mailbox/*/changes

… use of JMAP API templates

…bjects

* add Groupware APIs for creating and deleting addressbooks * add Groupware APIs for creating and deleting calendars * add JMAP APIs for creating and deleting addressbooks, calendars * add JMAP APIs to retrieve Principals * fix API tagging * move addressbook JMAP APIs into its own file * move addressbook Groupware APIs into its own file

…hods and more intelligence to the various request and response types to improve the use of template functions, reducing the risks of typos and copy/paste mistakes

* move ContactCard from jscontact to jmap, as it is actually a JMAP specification item, but also was causing too many issues with circular references from jscontact -> jmap * introduce Foo, Idable, GetRequest, GetResponse, etc... types and generics * first attempt at a Foo factory type for Mailboxes, needs to be expanded to further minimize repetition * add more specialized template functions to avoid repetition * introduce ChangesTemplate[T] for *Changes structs

* introduce jmap.Context to hold multiple parameters and shorten function calls * introduce SearchResultsTemplate

* make the JMAP internal API a bit more future-proof by passing ObjectType objects instead of the JMAP namespaces * remove the new attempt to contain operations even further using the Factory objects * move CalendarEvent operations to its own file, like everything else * fix email tests * ignore WS error when closing an already closed connection

* jmap: add UpdateContactCard and UpdateCalendarEvent funcs * use JSON marshalling and unmarshalling into a map for toPatch() implementations * add updating ContactCards and CalendarEvents to tests * add deleting ContactCards and CalendarEvents to tests * make query response totals work when the value is 0 * tests: use CreateContactCard and CreateCalendarEvent funcs to create objects in tests instead of using a different JMAP stack that works with untyped maps

…events

sonarqubecloud · 2026-04-13T14:55:49Z

Quality Gate failed

Failed conditions
72 Security Hotspots
3.7% Duplication on New Code (required ≤ 3%)
E Security Rating on New Code (required ≥ A)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

pbleser-oc self-assigned this Dec 9, 2025

pbleser-oc added Status:Needs-Review Type:Organizational Type:Maintenance E.g. technical debt, packaging, etc. and removed Type:Organizational labels Dec 9, 2025

pbleser-oc requested a review from butonic December 10, 2025 08:32

pbleser-oc marked this pull request as ready for review December 10, 2025 08:32

butonic reviewed Dec 10, 2025

View reviewed changes

services/auth-api/pkg/service/http/v0/service.go Outdated Show resolved Hide resolved

butonic reviewed Dec 10, 2025

View reviewed changes

services/groupware/DEVELOPER.md Outdated Show resolved Hide resolved

butonic reviewed Dec 10, 2025

View reviewed changes