What Is the /heartbeat API Endpoint in PicList?

The /heartbeat endpoint acts as a lightweight health check that returns a simple JSON payload to confirm the PicList local server is alive, allowing the Electron frontend to detect unresponsive states and trigger recovery actions.

The PicList image upload tool runs a tiny local HTTP server to bridge the Electron frontend with system-level operations. According to the kuingsmile/piclist source code, the /heartbeat route provides a critical keep-alive mechanism that enables the UI to verify server responsiveness without consuming significant resources.

How the /heartbeat Endpoint Works

The endpoint serves three primary responsibilities within PicList's architecture:

• Keep-alive verification – The UI periodically pings /heartbeat to confirm the local server process hasn't crashed or entered a zombie state.
• Health status reporting – It returns a minimal JSON response that the renderer process evaluates to decide whether to retry requests, restart the server, or display connection warnings.
• Zero-overhead design – No authentication requirements, empty request bodies, and fast 200 OK responses make the endpoint suitable for polling every few seconds.

Implementation in the Source Code

Route Registration in routerManager.ts

The endpoint definition lives in src/main/server/routerManager.ts, where the application registers the route using the shared Router instance:

// src/main/server/routerManager.ts
import router from './router'

router.any('/heartbeat', (req, res) => {
  // Simply answer that the service is alive
  res.json({ success: true })
})

Router Configuration in router.ts

The any method used above is defined in src/main/server/router.ts. This method registers the handler for both GET and POST HTTP verbs, ensuring the frontend can call the endpoint regardless of its specific HTTP client configuration.

Server Initialization in index.ts

The actual HTTP server that listens for these requests starts in src/main/server/index.ts. This file bootstraps the Express-like server that exposes the /heartbeat endpoint alongside other internal API routes.

Practical Usage Examples

Polling with fetch

From the renderer process or any frontend script, you can implement periodic health monitoring using the native fetch API:

// Example: periodic health check
function pingServer() {
  fetch('http://127.0.0.1:12345/heartbeat')
    .then(r => r.json())
    .then(data => {
      if (!data.success) {
        console.warn('PicList server heartbeat failed')
      }
    })
    .catch(err => console.error('Heartbeat error', err))
}

// Call every 5 seconds
setInterval(pingServer, 5000)

Using axios for Health Checks

If your integration prefers a library approach, axios provides cleaner async/await syntax:

import axios from 'axios'

async function checkHeartbeat() {
  try {
    const { data } = await axios.get('http://127.0.0.1:12345/heartbeat')
    console.log('Server OK:', data)
  } catch (e) {
    console.error('Heartbeat failed', e)
  }
}

Summary

• The /heartbeat endpoint in PicList returns { success: true } to signal that the local server is operational.
• It is registered in src/main/server/routerManager.ts using router.any(), supporting both GET and POST requests.
• The implementation prioritizes minimal overhead, making it safe to poll every few seconds from the Electron frontend.
• Source files src/main/server/router.ts and src/main/server/index.ts provide the routing logic and server initialization respectively.

Frequently Asked Questions

What response does the /heartbeat endpoint return?

The endpoint returns a JSON object with a success boolean set to true. According to the implementation in src/main/server/routerManager.ts, the response is generated via res.json({ success: true }), indicating the server process is alive and capable of handling requests.

Which HTTP methods does the /heartbeat endpoint support?

The endpoint accepts both GET and POST requests. The route registration uses router.any('/heartbeat', ...), defined in src/main/server/router.ts, which attaches the handler to multiple HTTP verbs simultaneously.

Where is the /heartbeat route defined in the PicList codebase?

The route handler is registered in src/main/server/routerManager.ts. The underlying Router class that provides the any method is defined in src/main/server/router.ts, while the server startup logic resides in src/main/server/index.ts.

Why does PicList use a simple heartbeat instead of WebSockets?

The heartbeat approach minimizes complexity and resource usage. A stateless HTTP call to /heartbeat requires no persistent connection management, works reliably through corporate proxies, and provides sufficient latency detection for detecting a crashed local server process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}