109 lines
5.5 KiB
C
109 lines
5.5 KiB
C
/* Trainlog Web Sessions V1 application service. */
|
|
#ifndef TRAINLOG_WEB_SESSIONS_H
|
|
#define TRAINLOG_WEB_SESSIONS_H
|
|
|
|
#include <stddef.h>
|
|
|
|
#include "trainlog/database.h"
|
|
#include "trainlog/status.h"
|
|
|
|
#define TRAINLOG_WEB_SESSIONS_PAGE_MAX 64U
|
|
#define TRAINLOG_WEB_SESSIONS_JSON_MAX (512U * 1024U)
|
|
|
|
typedef enum TrainlogWebSessionCollection {
|
|
TRAINLOG_WEB_SESSION_PREPARATIONS = 0,
|
|
TRAINLOG_WEB_SESSION_PROPOSALS,
|
|
TRAINLOG_WEB_SESSION_DRAFTS,
|
|
TRAINLOG_WEB_SESSION_HISTORY
|
|
} TrainlogWebSessionCollection;
|
|
|
|
typedef struct TrainlogWebSessionsPageQuery {
|
|
TrainlogWebSessionCollection collection;
|
|
size_t offset;
|
|
size_t limit;
|
|
const char *search;
|
|
} TrainlogWebSessionsPageQuery;
|
|
|
|
/*
|
|
* CONTRACT: every successful JSON-producing function below transfers one
|
|
* heap allocation through output_json; the caller owns it and releases it
|
|
* with free(). Borrowed input strings need only remain valid for the call.
|
|
*/
|
|
|
|
/*
|
|
* CONTRACT: database and query strings are borrowed for the call. On success,
|
|
* output_json is heap-owned by the caller and must be released with free().
|
|
* A page contains at most TRAINLOG_WEB_SESSIONS_PAGE_MAX rows plus a `more`
|
|
* flag derived from one additional row observed in the same read snapshot.
|
|
*/
|
|
TrainlogStatus trainlog_web_sessions_list_json(TrainlogDatabase *database,
|
|
const TrainlogWebSessionsPageQuery *query,
|
|
char **output_json,
|
|
size_t *output_size);
|
|
|
|
/* WHY: the Sleep agenda needs factual completed sessions without fetching one
|
|
* detail per row. CONTRACT: start/end are bounded ISO instants; intervals
|
|
* intersect [start,end), and a session with no valid end is a point at start.
|
|
* Pages are ordered by factual start and stable ID. No state is mutated.
|
|
* INVARIANT: the caller owns output_json and must paginate until more=false. */
|
|
TrainlogStatus trainlog_web_sessions_sport_json(TrainlogDatabase *database,
|
|
const char *start,
|
|
const char *end,
|
|
size_t offset,
|
|
size_t limit,
|
|
char **output_json,
|
|
size_t *output_size);
|
|
|
|
/* CONTRACT: kind is one of preparation, proposal, draft, or history. The
|
|
* returned detail is a factual snapshot and performs no lifecycle transition. */
|
|
TrainlogStatus trainlog_web_sessions_detail_json(TrainlogDatabase *database,
|
|
const char *kind,
|
|
const char *identity,
|
|
char **output_json,
|
|
size_t *output_size);
|
|
|
|
/* CONTRACT: the catalogue contains only currently selectable exercises. */
|
|
TrainlogStatus trainlog_web_sessions_catalog_json(TrainlogDatabase *database,
|
|
const char *search,
|
|
size_t offset,
|
|
size_t limit,
|
|
char **output_json,
|
|
size_t *output_size);
|
|
|
|
/*
|
|
* CONTRACT: save_body is a complete revision document and request_id is a
|
|
* durable idempotency key. expected_revision is empty only for creation.
|
|
* Validation and the head comparison occur in one immediate transaction.
|
|
*/
|
|
TrainlogStatus trainlog_web_sessions_save_json(TrainlogDatabase *database,
|
|
const char *preparation_id,
|
|
const char *expected_revision,
|
|
const char *request_id,
|
|
const char *save_body,
|
|
size_t save_body_size,
|
|
char **output_json,
|
|
size_t *output_size);
|
|
|
|
/* Creates one explicit immutable delivery for a ready current revision. */
|
|
TrainlogStatus trainlog_web_sessions_deliver_json(TrainlogDatabase *database,
|
|
const char *preparation_id,
|
|
const char *expected_revision,
|
|
const char *request_id,
|
|
char **output_json,
|
|
size_t *output_size);
|
|
|
|
/*
|
|
* CONTRACT: withdrawal is a logical, durable removal of one preparation.
|
|
* It preserves immutable revisions and every execution identity. Only the
|
|
* current revision may be withdrawn, and request_id makes response replay
|
|
* idempotent. Android delivery cancellation is completed by the versioned
|
|
* generation participant rather than by deleting delivery evidence here.
|
|
*/
|
|
TrainlogStatus trainlog_web_sessions_withdraw_json(TrainlogDatabase *database,
|
|
const char *preparation_id,
|
|
const char *expected_revision,
|
|
const char *request_id,
|
|
char **output_json,
|
|
size_t *output_size);
|
|
|
|
#endif
|