mirror/opencloud
1
0
Fork 0
mirror of https://github.com/opencloud-eu/opencloud.git synced 2026-02-10 22:19:17 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs(groupware): OpenAPI improvements

Browse Source 
* refactor some pkg/jmap and groupware methods to make more sense from
   an API point-of-view

 * add path parameter documentation, but automate it by injecting their
   definition into the OpenAPI YAML tree that is extracted from the
   source code using go-swagger as it is too cumbersome, repetitive and
   error-prine to document them in the source code; wrote a TypeScript
   file apidoc-process.ts to do so

 * add generating an offline HTML file for the OpenAPI documentation
   using redocly, and injecting a favicon into the resulting HTML; wrote
   a TypeScript file apidoc-postprocess-html.ts to do so
This commit is contained in:
Pascal Bleser
2025-09-05 14:36:54 +02:00
parent b171609376
commit 3968eedcc5
24 changed files with 2839 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
pkg/jmap/jmap_api.go
View File

@@ -31,5 +31,5 @@ const (
logDownloadUrl = "download-url"
logBlobId = "blob-id"
logUploadUrl = "download-url"
logSince = "since"
logSinceState = "since-state"
)

107
pkg/jmap/jmap_api_email.go
View File

@@ -30,6 +30,7 @@ type Emails struct {
State State `json:"state,omitempty"`
}
// Retrieve specific Emails by their id.
func (j *Client) GetEmails(accountId string, session *Session, ctx context.Context, logger *log.Logger, ids []string, fetchBodies bool, maxBodyValueBytes uint) (Emails, SessionState, Error) {
logger = j.logger(accountId, "GetEmails", session, logger)
@@ -54,8 +55,9 @@ func (j *Client) GetEmails(accountId string, session *Session, ctx context.Conte
})
}
func (j *Client) GetAllEmails(accountId string, session *Session, ctx context.Context, logger *log.Logger, mailboxId string, offset uint, limit uint, fetchBodies bool, maxBodyValueBytes uint) (Emails, SessionState, Error) {
logger = j.loggerParams(accountId, "GetAllEmails", session, logger, func(z zerolog.Context) zerolog.Context {
// Retrieve all the Emails in a given Mailbox by its id.
func (j *Client) GetAllEmailsInMailbox(accountId string, session *Session, ctx context.Context, logger *log.Logger, mailboxId string, offset uint, limit uint, fetchBodies bool, maxBodyValueBytes uint) (Emails, SessionState, Error) {
logger = j.loggerParams(accountId, "GetAllEmailsInMailbox", session, logger, func(z zerolog.Context) zerolog.Context {
return z.Bool(logFetchBodies, fetchBodies).Uint(logOffset, offset).Uint(logLimit, limit)
})
@@ -115,96 +117,15 @@ func (j *Client) GetAllEmails(accountId string, session *Session, ctx context.Co
})
}
type EmailsSince struct {
Destroyed []string `json:"destroyed,omitzero"`
HasMoreChanges bool `json:"hasMoreChanges,omitzero"`
NewState State `json:"newState"`
Created []Email `json:"created,omitempty"`
Updated []Email `json:"updated,omitempty"`
State State `json:"state,omitempty"`
}
func (j *Client) GetEmailsInMailboxSince(accountId string, session *Session, ctx context.Context, logger *log.Logger, mailboxId string, since string, fetchBodies bool, maxBodyValueBytes uint, maxChanges uint) (EmailsSince, SessionState, Error) {
logger = j.loggerParams(accountId, "GetEmailsInMailboxSince", session, logger, func(z zerolog.Context) zerolog.Context {
return z.Bool(logFetchBodies, fetchBodies).Str(logSince, since)
})
changes := MailboxChangesCommand{
AccountId: accountId,
SinceState: since,
}
if maxChanges > 0 {
changes.MaxChanges = maxChanges
}
getCreated := EmailGetRefCommand{
AccountId: accountId,
FetchAllBodyValues: fetchBodies,
IdRef: &ResultReference{Name: CommandMailboxChanges, Path: "/created", ResultOf: "0"},
}
if maxBodyValueBytes > 0 {
getCreated.MaxBodyValueBytes = maxBodyValueBytes
}
getUpdated := EmailGetRefCommand{
AccountId: accountId,
FetchAllBodyValues: fetchBodies,
IdRef: &ResultReference{Name: CommandMailboxChanges, Path: "/updated", ResultOf: "0"},
}
if maxBodyValueBytes > 0 {
getUpdated.MaxBodyValueBytes = maxBodyValueBytes
}
cmd, err := request(
invocation(CommandMailboxChanges, changes, "0"),
invocation(CommandEmailGet, getCreated, "1"),
invocation(CommandEmailGet, getUpdated, "2"),
)
if err != nil {
logger.Error().Err(err)
return EmailsSince{}, "", simpleError(err, JmapErrorInvalidJmapRequestPayload)
}
return command(j.api, logger, ctx, session, j.onSessionOutdated, cmd, func(body *Response) (EmailsSince, Error) {
var mailboxResponse MailboxChangesResponse
err = retrieveResponseMatchParameters(body, CommandMailboxChanges, "0", &mailboxResponse)
if err != nil {
logger.Error().Err(err)
return EmailsSince{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
}
var createdResponse EmailGetResponse
err = retrieveResponseMatchParameters(body, CommandEmailGet, "1", &createdResponse)
if err != nil {
logger.Error().Err(err)
return EmailsSince{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
}
var updatedResponse EmailGetResponse
err = retrieveResponseMatchParameters(body, CommandEmailGet, "2", &updatedResponse)
if err != nil {
logger.Error().Err(err)
return EmailsSince{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
}
return EmailsSince{
Destroyed: mailboxResponse.Destroyed,
HasMoreChanges: mailboxResponse.HasMoreChanges,
NewState: mailboxResponse.NewState,
Created: createdResponse.List,
Updated: createdResponse.List,
State: createdResponse.State,
}, nil
})
}
func (j *Client) GetEmailsSince(accountId string, session *Session, ctx context.Context, logger *log.Logger, since string, fetchBodies bool, maxBodyValueBytes uint, maxChanges uint) (EmailsSince, SessionState, Error) {
// Get all the Emails that have been created, updated or deleted since a given state.
func (j *Client) GetEmailsSince(accountId string, session *Session, ctx context.Context, logger *log.Logger, sinceState string, fetchBodies bool, maxBodyValueBytes uint, maxChanges uint) (MailboxChanges, SessionState, Error) {
logger = j.loggerParams(accountId, "GetEmailsSince", session, logger, func(z zerolog.Context) zerolog.Context {
return z.Bool(logFetchBodies, fetchBodies).Str(logSince, since)
return z.Bool(logFetchBodies, fetchBodies).Str(logSinceState, sinceState)
})
changes := EmailChangesCommand{
AccountId: accountId,
SinceState: since,
SinceState: sinceState,
}
if maxChanges > 0 {
changes.MaxChanges = maxChanges
@@ -233,32 +154,32 @@ func (j *Client) GetEmailsSince(accountId string, session *Session, ctx context.
invocation(CommandEmailGet, getUpdated, "2"),
)
if err != nil {
return EmailsSince{}, "", simpleError(err, JmapErrorInvalidJmapRequestPayload)
return MailboxChanges{}, "", simpleError(err, JmapErrorInvalidJmapRequestPayload)
}
return command(j.api, logger, ctx, session, j.onSessionOutdated, cmd, func(body *Response) (EmailsSince, Error) {
return command(j.api, logger, ctx, session, j.onSessionOutdated, cmd, func(body *Response) (MailboxChanges, Error) {
var changesResponse EmailChangesResponse
err = retrieveResponseMatchParameters(body, CommandEmailChanges, "0", &changesResponse)
if err != nil {
logger.Error().Err(err)
return EmailsSince{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
return MailboxChanges{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
}
var createdResponse EmailGetResponse
err = retrieveResponseMatchParameters(body, CommandEmailGet, "1", &createdResponse)
if err != nil {
logger.Error().Err(err)
return EmailsSince{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
return MailboxChanges{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
}
var updatedResponse EmailGetResponse
err = retrieveResponseMatchParameters(body, CommandEmailGet, "2", &updatedResponse)
if err != nil {
logger.Error().Err(err)
return EmailsSince{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
return MailboxChanges{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
}
return EmailsSince{
return MailboxChanges{
Destroyed: changesResponse.Destroyed,
HasMoreChanges: changesResponse.HasMoreChanges,
NewState: changesResponse.NewState,

84
pkg/jmap/jmap_api_mailbox.go
View File

@@ -4,6 +4,7 @@ import (
"context"
"github.com/opencloud-eu/opencloud/pkg/log"
"github.com/rs/zerolog"
)
type MailboxesResponse struct {
@@ -85,3 +86,86 @@ func (j *Client) SearchMailboxes(accountId string, session *Session, ctx context
return Mailboxes{Mailboxes: response.List, State: response.State}, nil
})
}
type MailboxChanges struct {
Destroyed []string `json:"destroyed,omitzero"`
HasMoreChanges bool `json:"hasMoreChanges,omitzero"`
NewState State `json:"newState"`
Created []Email `json:"created,omitempty"`
Updated []Email `json:"updated,omitempty"`
State State `json:"state,omitempty"`
}
// Retrieve Email changes in a given Mailbox since a given state.
func (j *Client) GetMailboxChanges(accountId string, session *Session, ctx context.Context, logger *log.Logger, mailboxId string, sinceState string, fetchBodies bool, maxBodyValueBytes uint, maxChanges uint) (MailboxChanges, SessionState, Error) {
logger = j.loggerParams(accountId, "GetMailboxChanges", session, logger, func(z zerolog.Context) zerolog.Context {
return z.Bool(logFetchBodies, fetchBodies).Str(logSinceState, sinceState)
})
changes := MailboxChangesCommand{
AccountId: accountId,
SinceState: sinceState,
}
if maxChanges > 0 {
changes.MaxChanges = maxChanges
}
getCreated := EmailGetRefCommand{
AccountId: accountId,
FetchAllBodyValues: fetchBodies,
IdRef: &ResultReference{Name: CommandMailboxChanges, Path: "/created", ResultOf: "0"},
}
if maxBodyValueBytes > 0 {
getCreated.MaxBodyValueBytes = maxBodyValueBytes
}
getUpdated := EmailGetRefCommand{
AccountId: accountId,
FetchAllBodyValues: fetchBodies,
IdRef: &ResultReference{Name: CommandMailboxChanges, Path: "/updated", ResultOf: "0"},
}
if maxBodyValueBytes > 0 {
getUpdated.MaxBodyValueBytes = maxBodyValueBytes
}
cmd, err := request(
invocation(CommandMailboxChanges, changes, "0"),
invocation(CommandEmailGet, getCreated, "1"),
invocation(CommandEmailGet, getUpdated, "2"),
)
if err != nil {
logger.Error().Err(err)
return MailboxChanges{}, "", simpleError(err, JmapErrorInvalidJmapRequestPayload)
}
return command(j.api, logger, ctx, session, j.onSessionOutdated, cmd, func(body *Response) (MailboxChanges, Error) {
var mailboxResponse MailboxChangesResponse
err = retrieveResponseMatchParameters(body, CommandMailboxChanges, "0", &mailboxResponse)
if err != nil {
logger.Error().Err(err)
return MailboxChanges{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
}
var createdResponse EmailGetResponse
err = retrieveResponseMatchParameters(body, CommandEmailGet, "1", &createdResponse)
if err != nil {
logger.Error().Err(err)
return MailboxChanges{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
}
var updatedResponse EmailGetResponse
err = retrieveResponseMatchParameters(body, CommandEmailGet, "2", &updatedResponse)
if err != nil {
logger.Error().Err(err)
return MailboxChanges{}, simpleError(err, JmapErrorInvalidJmapResponsePayload)
}
return MailboxChanges{
Destroyed: mailboxResponse.Destroyed,
HasMoreChanges: mailboxResponse.HasMoreChanges,
NewState: mailboxResponse.NewState,
Created: createdResponse.List,
Updated: createdResponse.List,
State: createdResponse.State,
}, nil
})
}

2
pkg/jmap/jmap_integration_test.go
View File

@@ -449,7 +449,7 @@ func TestWithStalwart(t *testing.T) {
}
{
resp, sessionState, err := j.GetAllEmails(accountId, session, ctx, logger, inboxId, 0, 0, false, 0)
resp, sessionState, err := j.GetAllEmailsInMailbox(accountId, session, ctx, logger, inboxId, 0, 0, false, 0)
require.NoError(err)
require.Equal(session.State, sessionState)

2
pkg/jmap/jmap_test.go
View File

@@ -156,7 +156,7 @@ func TestRequests(t *testing.T) {
require.Len(folders.Mailboxes, 5)
require.NotEmpty(sessionState)
emails, sessionState, err := client.GetAllEmails("a", &session, ctx, &logger, "Inbox", 0, 0, true, 0)
emails, sessionState, err := client.GetAllEmailsInMailbox("a", &session, ctx, &logger, "Inbox", 0, 0, true, 0)
require.NoError(err)
require.Len(emails.Emails, 3)
require.NotEmpty(sessionState)