xBrowserSync API (Go)

A Go port of the xBrowserSync REST API service. This is a drop-in replacement for the original Node.js API - existing browser extensions and mobile apps connect to it without any changes.

xBrowserSync is a free tool for syncing browser data between different browsers and devices, built for privacy and anonymity. The server stores only encrypted, opaque data - all encryption and decryption happens client-side.

• Go 1.21 or later (for building)
• MongoDB 4.x or later

git clone https://github.com/navin09/xbrowsersync-api-go.git
cd xbrowsersync-api-go
make build
./bin/xbrowsersync-api

The server starts on http://127.0.0.1:8080/ by default.

1. Create a database user and the required indexes in the mongo shell:

   use admin
   db.createUser({
     user: "xbrowsersyncdb",
     pwd: "[password]",
     roles: [
       { role: "readWrite", db: "xbrowsersync" },
       { role: "readWrite", db: "xbrowsersynctest" }
     ]
   })
   
   use xbrowsersync
   db.newsynclogs.createIndex({ "expiresAt": 1 }, { expireAfterSeconds: 0 })
   db.newsynclogs.createIndex({ "ipAddress": 1 })
   

2. Set the database credentials via environment variables:

   export XBROWSERSYNC_DB_USER=xbrowsersyncdb
   export XBROWSERSYNC_DB_PWD=[password]
   

3. If exposing your service publicly, add a TTL index to automatically delete syncs that haven't been accessed for 3 weeks:

   use xbrowsersync
   db.bookmarks.createIndex({ "lastAccessed": 1 }, { expireAfterSeconds: 1814400 })
   

Configuration is managed through two JSON files in the config/ directory:

• settings.default.json - contains all settings with their default values. Do not edit this file.
• settings.json - your overrides. Create this file and include only the settings you want to change.

To customise your instance, copy the settings you want to override from settings.default.json into a new config/settings.json. For example, to set a welcome message and restrict the service to specific origins:

{
  "status": {
    "message": "Welcome to my xBrowserSync service"
  },
  "allowedOrigins": ["https://mybrowser.example.com"]
}

Any settings not present in settings.json fall back to the defaults. This means future updates to default values are picked up automatically - only override what you need.

Database credentials can also be supplied via environment variables (XBROWSERSYNC_DB_USER, XBROWSERSYNC_DB_PWD), which take precedence over empty values in the config files.

make build        # builds bin/xbrowsersync-api
make test         # runs unit tests
make lint         # runs golangci-lint (if installed)
make clean        # removes bin/

To set a custom version string:

make build VERSION=2.0.0

make run
# or
./bin/xbrowsersync-api

The binary looks for config/ relative to the working directory.

All endpoints support API versioning via the Accept-Version header.

Build and run with Docker:

docker build -t xbrowsersync-api .
docker run -p 8080:8080 \
  -e XBROWSERSYNC_DB_USER=xbrowsersyncdb \
  -e XBROWSERSYNC_DB_PWD=[password] \
  -v /path/to/settings.json:/config/settings.json \
  xbrowsersync-api

The image is ~15MB (distroless base). Mount your settings.json to override defaults - at minimum you'll need to set db.host to point at your MongoDB instance.

Cloud Run runs the Docker container serverlessly - it scales to zero when idle and you only pay for requests.

• A MongoDB Atlas cluster (free tier works). Cloud Run can't host MongoDB, so you need an external database.
• Google Cloud SDK installed and a GCP project configured.

1. Create a config/settings.json for Cloud Run:

   {
     "db": {
       "host": "your-cluster.mongodb.net",
       "name": "xbrowsersync",
       "useSRV": true
     },
     "server": {
       "host": "0.0.0.0",
       "behindProxy": true
     },
     "log": {
       "file": {
         "enabled": false
       }
     }
   }

   Key settings: host must be 0.0.0.0 (Cloud Run requirement), behindProxy should be true (Cloud Run terminates TLS), and file logging is disabled (use stdout - Cloud Run captures it automatically).

2. Build and push the container:

   gcloud builds submit --tag gcr.io/YOUR_PROJECT/xbrowsersync-api
   

3. Deploy to Cloud Run:

   gcloud run deploy xbrowsersync-api \
     --image gcr.io/YOUR_PROJECT/xbrowsersync-api \
     --port 8080 \
     --set-env-vars XBROWSERSYNC_DB_USER=xbrowsersyncdb,XBROWSERSYNC_DB_PWD=[password] \
     --allow-unauthenticated
   

4. Point your xBrowserSync extension at the Cloud Run URL.

This is a faithful port of the Node.js xBrowserSync API. It uses the same:

• MongoDB collections and schema (including binary UUID storage)
• JSON config file format
• API contract (endpoints, request/response shapes, error codes, HTTP status codes)
• Semver-based API version routing

Existing xBrowserSync clients work without modification. Data created by the Node.js server is fully readable by the Go server and vice versa.

GPL-3.0