mirror of
https://codeberg.org/timelimit/timelimit-server.git
synced 2025-10-03 09:49:32 +02:00
117 lines
3.8 KiB
Markdown
117 lines
3.8 KiB
Markdown
# /sync
|
|
|
|
This endpoint is used by clients for syncing.
|
|
|
|
## the sync process
|
|
|
|
- the client pushes all actions (eventually in chunks)
|
|
- all actions are numbered so that the server can ignore it if the client sends an action multiple times (e.g. due to connectivity issues)
|
|
- in case something goes wrong, the server asks the client to do a full query when pulling the status the next time
|
|
- the client pulls the status
|
|
- the client sends a summary of the current status
|
|
- the server does not send the data which the client already knows
|
|
- in case the client is unauthorized, then the client checks against /sync/is-device-removed
|
|
- if it tells the client that it was really removed, then the client resets itself
|
|
|
|
## possible sync triggers
|
|
|
|
- periodically/ by the time (e.g. every hour, not all 10 seconds)
|
|
- the [websocket](./websocket.md) for syncing as soon as something was changed by an other client
|
|
- changes/ actions at the client itself
|
|
|
|
## POST /sync/push-actions
|
|
|
|
Use this to sync actions to the server.
|
|
|
|
### request
|
|
|
|
see [this JSON schema](../schema/clientpushchangesrequest.md)
|
|
|
|
the encoded actions are stringified JSON objects of one of this schemes:
|
|
- [serialized app logic action](../schema/serializedapplogicaction.md)
|
|
- [serialized parent action](../schema/serializedparentaction.md)
|
|
- [serialized child action](../schema/serializedchildaction.md)
|
|
|
|
The request must not contain more than 50 actions. The request may contain less than 50
|
|
actions.
|
|
|
|
The sequence numbers must be a increasing sequence per device.
|
|
|
|
#### integrity
|
|
|
|
The integrity field of a action may have got one of the following values:
|
|
|
|
- an empty string when no user authentication is required/ for app logic actions (e.g. incrementing the used time)
|
|
- the string ``device`` in case of parent actions if a parent is assigned to the device and asking for the password was disabled
|
|
- ``sha512(sequence number as string with the base 10 + the device id as string + the hash of the user password using the second salt as string + the encoded action as string)`` for parent and child actions
|
|
|
|
In case of a invalid integrity value, the action is ignored and the client is told to do a full sync
|
|
|
|
### response
|
|
|
|
On a invalid request body: HTTP status code 400 Bad request
|
|
|
|
On a invalid auth token: HTTP status code 401 Unauthorized
|
|
|
|
On success: JSON object with the property ``shouldDoFullSync`` - example: ``{"shouldDoFullSync": false}``
|
|
|
|
### error handling
|
|
|
|
If a action has got a invalid ``integrity`` or ``encodedAction``, then only this action
|
|
is ignored and ``shouldDoFullSync`` will be true.
|
|
|
|
## POST /sync/pull-status
|
|
|
|
Use this to pull the current status from the server.
|
|
|
|
### request
|
|
|
|
see [this JSON schema](../schema/clientpullchangesrequest.md)
|
|
|
|
### response
|
|
|
|
On a invalid request body: HTTP status code 400 Bad request
|
|
|
|
On a invalid auth token: HTTP status code 401 Unauthorized
|
|
|
|
On success: see [this JSON schema](../schema/serverdatastatus.md)
|
|
|
|
## POST /sync/report-removed
|
|
|
|
Use this to report that TimeLimit is/ was reset.
|
|
|
|
### request
|
|
|
|
see [this JSON schema](../schema/requestwithauthtoken.md)
|
|
|
|
### response
|
|
|
|
On a invalid request body: http status code 400 Bad request
|
|
|
|
On a invalid/ unknown auth token: http status code 500 Internal Server Error
|
|
|
|
On success: ``{"ok": true}``
|
|
|
|
### error handling
|
|
|
|
If a removed device reports that it is removed, then it is ignored and handled
|
|
as success.
|
|
|
|
## POST /sync/is-device-removed
|
|
|
|
Use this to check if the device was removed.
|
|
|
|
Background: This checks if the auth token is in a list of known old auth tokens.
|
|
This ensures that an empty database at the server does not trigger the client reset feature.
|
|
|
|
### request
|
|
|
|
see [this JSON schema](../schema/requestwithauthtoken.md)
|
|
|
|
### response
|
|
|
|
On a invalid request body: http status code 400 bad request
|
|
|
|
object with the property ``isDeviceRemoved`` of the type boolean
|
|
|
|
example response: ``{"isDeviceRemoved": false}``
|