Healthcheck API

[JCKodel]

Sometimes, Powersync is in an invalid state and not much information is sent to the client about why.

For example:

{"level":"error","message":"Replication error Publication 'powersync' does not exist. Run: `CREATE PUBLICATION powersync FOR ALL TABLES`, or read the documentation for details."
...

It also stays in an invalid state when something is wrong with sync_rules.yaml (I see the exactly reason only on docker desktop logs panel).

It would be nice a GET endpoint to check if there is any error in the service and returning 200 or 500.

That could be used in docker compose healthcheck.

[stevensJourney]

There currently is an undocumented admin API route which might help with this.

A POST request to http://localhost:8080/api/admin/v1/diagnostics should return some diagnostics information. The authentication is provided with a predefined set of admin tokens.

In the config YAML file you can define the tokens:

api:
  tokens:
    - [super secret token]

Then you can use a defined token in the Authorization header of the request.

curl -X POST http://localhost:8080/api/admin/v1/diagnostics \
     -H "Authorization: Bearer [super secret token]" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{}'

[JCKodel]

@stevensJourney Thank you.

For those interested in, that's what I got:

healthcheck:
  test: 'curl -X POST http://localhost:${PS_PORT}/api/admin/v1/diagnostics -H "Authorization: Bearer ${PS_API_TOKEN}" -H "Content-Type: application/json" -H "Accept: application/json" -d "{}" | grep "\"errors\":\[{" && exit 1 || exit 0'
  interval: 5s
  timeout: 1s
  retries: 15

[guillempuche]

Hi, you put healthcheck in the config.yml, right?

[JCKodel]

Nop. In docker-compose.yaml.

[guillempuche]

Cool. Something like:

services:
  powersync:
    image: journeyapps/powersync-service:latest
    command: ["start", "-r", "unified",]
    depends_on:
      mongo-rs-init:
        condition: service_completed_successfully
    environment:
      POWERSYNC_CONFIG_PATH: /config/config.yml
      PS_POSTGRES_URI: postgresql://postgres:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
      PS_API_TOKEN: abcd1234
      PS_PORT: 8080
    networks:
      - supabase_network
    ports:
      - 8080:8080
    restart: unless-stopped
    volumes:
      - ./config.yml:/config/config.yml
      - ./sync_rules.yml:/config/sync_rules.yml
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    healthcheck:
      test: 'curl -X POST http://localhost:${PS_PORT}/api/admin/v1/diagnostics -H "Authorization: Bearer ${PS_API_TOKEN}" -H "Content-Type: application/json" -H "Accept: application/json" -d "{}" | grep "\"errors\":\[{" && exit 1 || exit 0'
      interval: 5s
      timeout: 1s
      retries: 15
   ...

[DominicGBauer]

Hi @JCKodel and @guillempuche you can now use the /probes/liveness endpoint for your healthchecks :).

Example below:

# This requires image: journeyapps/powersync-service:0.5.8 or later
     healthcheck:
       test: ["CMD", "node", "-e", "fetch('http://localhost:${PS_PORT}/probes/liveness').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))"]
       interval: 5s
       timeout: 1s
       retries: 15

[guillempuche]

Ohhh, an improvement of DX!
I'll apply it.

[JCKodel]

Hi @JCKodel and @guillempuche you can now use the /probes/liveness endpoint for your healthchecks :).

Example below:

# This requires image: journeyapps/powersync-service:0.5.8 or later
     healthcheck:
       test: ["CMD", "node", "-e", "fetch('http://localhost:${PS_PORT}/probes/liveness').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))"]
       interval: 5s
       timeout: 1s
       retries: 15

@DominicGBauer This actually doesn't work at all! For instance: when initiating a PowerSync container that could not reach the Postgres database, this endpoint just returned 200. Also, when there are errors in the sync-rules file, this also returns 200.

[rkistner]

@JCKodel Note that there has been some recent fixes & improvements to these APIs here: #254

However, these are still only very basic healthcheck APIs intended for the specific container, for use by for example Kubernetes probes or Docker Compose health checks, to see when the process is ready or when it should be restarted.

It does not cover more general instance status, such as database not reachable, since that would typically not be fixed by a container restart.

For those types of checks, the diagnostics API mentioned above is a better fit.