Bark EdgeOne

中文（中国）

A Bark push notification server implementation for EdgeOne Pages Edge Functions, enabling distributed push notification delivery on edge nodes worldwide.

Deployment

Choose your preferred deployment method:

Method 1: Command Line Deployment (Recommended)

Prerequisites

• Node.js 18+
• Git

Step 1: Clone the Repository and Install Dependencies

# Clone the repository
git clone https://github.com/AkinoKaede/bark-edgeone.git
cd bark-edgeone

# Install dependencies
npm install

Step 2: Login to EdgeOne

# Login to your EdgeOne account
npx edgeone login

This will open a browser window for authentication.

Step 3: Link Project

# Link to existing project or create new one
npx edgeone link

Enter your project name. If the project doesn't exist, you'll be prompted to create it.

Step 4: Create and Bind KV Namespace

KV namespace must be configured via the web dashboard:

1. Go to EdgeOne → Service Overview (default page)
2. Navigate to KV Storage → Create Namespace
3. Name it bark-kv (or any name you prefer)
4. Go to EdgeOne → Service Overview → Your Project Name
5. Navigate to KV Storage → Bind Namespace
6. Select bark-kv and set binding name to KV_STORAGE
7. Save the binding

Step 6: Configure Environment Variables

# Generate a secure proxy secret (HIGHLY RECOMMENDED)
export PROXY_SECRET=$(openssl rand -hex 32)

# Set proxy secret (highly recommended for security)
npx edgeone pages env set APNS_PROXY_SECRET "$PROXY_SECRET"

# Optional: Set authentication credentials
npx edgeone pages env set AUTH_CREDENTIALS "admin:your-secure-password"

# Optional: Set batch push limit
npx edgeone pages env set MAX_BATCH_PUSH_COUNT "64"

# Optional: Configure custom APNs credentials (only if you have your own)
# Most users don't need these - default values work for Bark app
# npx edgeone pages env set APNS_TOPIC "me.fin.bark"
# npx edgeone pages env set APNS_KEY_ID "YOUR_KEY_ID"
# npx edgeone pages env set APNS_TEAM_ID "YOUR_TEAM_ID"
# npx edgeone pages env set APNS_PRIVATE_KEY "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"

Important:

• APNS_PROXY_SECRET is highly recommended for securing the proxy endpoint
• APNs credentials (APNS_TOPIC, APNS_KEY_ID, etc.) are optional - most users don't need them
• See docs/en/configuration/env.md for complete documentation

Step 7: Deploy

npx edgeone pages deploy

---

Method 2: Web Dashboard Deployment

Step 1: Fork Repository

1. Go to https://github.com/AkinoKaede/bark-edgeone
2. Click Fork button in the top-right corner
3. Fork the repository to your GitHub account

Step 2: Create Project and Connect GitHub

1. Go to EdgeOne Pages Dashboard
2. Click Create Project
3. Select GitHub Integration
4. Connect your GitHub account (if not already connected)
5. Select your forked bark-edgeone repository
6. Click Deploy

The build configuration is automatically loaded from edgeone.json in the repository.

Step 3: Create KV Namespace

1. Go to EdgeOne → Service Overview (default page)
2. Navigate to KV Storage → Create Namespace
3. Name it bark-kv (or any name you prefer)
4. Click Create

Step 4: Bind KV Namespace

1. Go to EdgeOne → Service Overview → Your Project Name
2. Navigate to KV Storage → Bind Namespace
3. Select bark-kv and set binding name to KV_STORAGE
4. Save the binding

Step 5: Configure Environment Variables

1. In your project dashboard, navigate to Settings → Environment Variables
2. Add the following variables:

Highly Recommended:

APNS_PROXY_SECRET = <generate using: openssl rand -hex 32>

Optional Variables:

AUTH_CREDENTIALS = admin:your-secure-password
MAX_BATCH_PUSH_COUNT = 64

Custom APNs Credentials (only if you have your own - most users don't need these):

APNS_TOPIC = me.fin.bark
APNS_KEY_ID = YOUR_KEY_ID
APNS_TEAM_ID = YOUR_TEAM_ID
APNS_PRIVATE_KEY = -----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----

3. Click Save

Important:

• APNS_PROXY_SECRET is highly recommended for securing the proxy endpoint
• APNs credentials are optional - default values work for the Bark app
• See docs/en/configuration/env.md for complete documentation

Step 6: Deploy

Push to your forked repository to trigger automatic deployment.

Test Your Deployment

1. Go to your project's Domain Management page
2. view your project's domain
3. Test the health endpoint:

curl https://your-domain.edgeone.cool/api/healthz

# Expected response: ok

---

Post-Deployment Configuration

Custom Domain (Optional)

1. In your project page, navigate to Domain Management
2. Click Add Custom Domain
3. Enter your domain name
4. Configure DNS records as instructed
5. Wait for SSL certificate provisioning

Known Issues

EdgeOne Pages KV Eventual Consistency

Issue: EdgeOne Pages KV storage only guarantees eventual consistency. After device registration, there may be a delay before the device token becomes available for push notifications.

Impact:

• Typical delay: A few seconds
• Maximum delay: Up to 1 hour (in rare cases)
• During this period, push notifications to newly registered devices may fail

Workaround:

• Wait a few seconds after registration before sending the first push notification
• Implement retry logic in your client applications
• This is a platform limitation and cannot be avoided

HTTP/2 Proxy Requirement

Issue: EdgeOne Edge Functions Runtime currently does not support HTTP/2 in the fetch API, which is required by Apple Push Notification service (APNs).

Current Solution:

• We use Node Functions as an HTTP/2 reverse proxy (/apns-proxy)
• Edge Functions forward APNs requests to the Node Functions proxy
• The proxy handles HTTP/2 communication with Apple's servers

Routing Limitation:

• Due to EdgeOne routing constraints, all Edge Functions are placed under /api/*
• This prevents conflicts between Edge Functions catch-all routes and Node Functions

Future Changes (Breaking):

• Once EdgeOne Edge Functions Runtime supports HTTP/2 in fetch:
  • The Node Functions proxy will be removed
  • API paths will be moved from /api/* to /* (breaking change)
  • Example: /api/push → /push, /api/register → /register

Migration Plan:

• When HTTP/2 support is added, we will:
  1. Announce the breaking change with a migration period
  2. Provide redirect rules for backward compatibility
  3. Update documentation with new endpoints

Local Development

# Start local development server
npx edgeone pages dev

# Server will be available at http://localhost:8088

Project Structure

bark-edgeone/
├── edge-functions/          # EdgeOne Edge Functions
│   └── api/                 # All API endpoints under /api
│       ├── push.ts          # POST /api/push
│       ├── register/        # /api/register/*
│       ├── ping.ts          # GET /api/ping
│       ├── healthz.ts       # GET /api/healthz
│       ├── info.ts          # GET /api/info
│       └── [[default]].ts   # V1 API catch-all
├── node-functions/          # Node.js Functions
│   └── apns-proxy/          # HTTP/2 proxy for APNs
├── src/
│   ├── apns/                # APNs client and utilities
│   ├── handlers/            # Business logic handlers
│   ├── types/               # TypeScript type definitions
│   └── utils/               # Helper functions
├── docs/                    # Documentation
│   ├── en/                  # English documentation
│   │   └── configuration/   # Configuration guides
│   │       └── env.md       # Environment variables guide
│   └── zh-cn/               # Chinese documentation
│       └── configuration/   # Configuration guides
│           └── env.md       # Environment variables guide
└── AGENTS.md                # Development guidelines

Contributing

Contributions are welcome! Please read Development Overview for development guidelines.

License

SPDX-License-Identifier: Apache-2.0

Acknowledgments

• Bark
• Bark Server