https://github.com/voxelum/xmcl-web-api
The web api implementation of XMCL
https://github.com/voxelum/xmcl-web-api
deno deno-deploy oak
Last synced: about 2 months ago
JSON representation
The web api implementation of XMCL
- Host: GitHub
- URL: https://github.com/voxelum/xmcl-web-api
- Owner: Voxelum
- Created: 2022-06-25T15:08:37.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-05-25T12:13:14.000Z (about 1 year ago)
- Last Synced: 2025-06-02T07:38:58.703Z (about 1 year ago)
- Topics: deno, deno-deploy, oak
- Language: TypeScript
- Homepage:
- Size: 142 KB
- Stars: 0
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# XMCL Web API
This repository contains the server-side code for the X-Minecraft Launcher (XMCL) web API. It provides various backend services that support the launcher functionality.
## Overview
The XMCL Web API serves multiple functions:
- Provides launcher update notifications and release information
- Manages real-time communication for multiplayer sessions
- Handles translations for mod descriptions and UI elements
- Offers WebRTC services for peer-to-peer connections
- Supports authentication with various services
## Architecture
The API is implemented in multiple ways to ensure global availability and reliability:
1. **Primary Service (Deno)** - Hosted on Deno Deploy
- Entry point: `index.ts`
- Global availability outside mainland China
- Uses MongoDB for data storage
2. **Backup Service (Azure Functions)** - Written in TypeScript
- Entry point: `azure/index.ts`
- Uses the Azure Functions JavaScript/TypeScript runtime
- Provides fallback capabilities if the primary service is unavailable
3. **Alibaba Cloud Function Service (Deno)** - Uses compiled binary
- Entry point: Compiled Deno binary via `aliyun/bootstrap`
- Alternative deployment option for better access in mainland China
- Uses `deno compile` to create a standalone executable
4. **Mainland China Service** - Specialized version in Go
- Entry point: `main.go`
- Optimized for access within mainland China
- Contains adaptations for the Chinese network environment
## API Endpoints
### Primary Service (Deno)
- `/latest` - Provides information about the latest launcher releases
- `/releases/:filename` - Access to launcher release files with redirection to GitHub
- `/notifications` - System notifications for launcher users from GitHub issues
- `/flights` - Feature flight information for gradual rollouts
- `/translation` - Translation services for mod descriptions (Modrinth and CurseForge)
- `/group/:id` - Real-time WebSocket communication for launcher user groups
- `/rtc/official` - WebRTC signaling for peer connections
- `/zulu` - Custom endpoint for specific launcher functionality
- `/elyby/authlib` - Authentication library access
- `/modrinth/auth` - Modrinth authentication integration
- `/kook-badge` - Access to KOOK integration information
### Backup Service (Azure Functions - Go)
- `/latest` - Similar to Deno service, provides launcher release information
- `/notifications` - Provides notifications from GitHub issues
- `/flights` - Feature flight configuration
- `/zulu` - Proxies to xmcl-static-resource repository
- `/appx` - Handles Windows appx file distribution with proxy support for Chinese users
### Mainland China Service (Go)
- `/group/:id` - Real-time WebSocket communication for groups
- `/translation` - Translation services for mod descriptions
- `/rtc/official` - WebRTC signaling service
## Environment Variables
### Primary Service (Deno)
- `MONGO_CONNECION_STRING` - Alternative name for MongoDB connection string
- `MONGODB_NAME` - Database name (default: "xmcl-api")
- `GITHUB_PAT` - GitHub Personal Access Token for API access
- `OPENAI_API_KEY` - API key for translation services using DeepSeek API
- `RTC_SECRET` - Secret for WebRTC services
- `CURSEFORGE_KEY` - API key for CurseForge integration
- `MODRINTH_SECRET` - Secret for Modrinth authentication integration
- `TURNS` - TURN server configuration (format: "realm:ip,realm:ip")
### Backup Service (Azure Functions - TypeScript)
- `GITHUB_PAT` - GitHub Personal Access Token for API access
- `FUNCTIONS_CUSTOMHANDLER_PORT` - Port for Azure Functions custom handler (legacy)
### Mainland China Service (Go)
- `MONGO_CONNECION_STRING` - MongoDB connection string
- `MONGODB_NAME` - Database name (default: "xmcl-api")
- `CURSEFORGE_KEY` - API key for CurseForge integration
- `RTC_SECRET` - Secret for WebRTC services
- `TURNS` - TURN server configuration (format: "realm:ip,realm:ip")
## Development
### Prerequisites
- [Deno](https://deno.land/) for the primary service
- [Go](https://golang.org/) for the Azure Functions and China service
- [MongoDB](https://www.mongodb.com/) for data storage
- Azure Functions Core Tools (for local Azure Functions testing)
### Local Development
```bash
# Run the Deno service locally
deno run --allow-net --allow-read --allow-env index.ts
# Build and run the Go service for China
go build main.go
./main
# Run the Azure Functions service locally
deno run build:fn
func start
```
## Deployment
### Deno Deploy
The primary service is deployed on Deno Deploy, which automatically deploys from the main branch.
### Azure Functions
For Azure Functions deployment, use the Azure CLI or Azure Portal:
```bash
az functionapp deployment source config-zip -g myResourceGroup -n myFunctionApp --src ./azure.zip
```
### Alibaba Cloud Function
The Deno service can be deployed to Alibaba Cloud Function using Serverless Devs with a compiled binary:
```bash
# Install Serverless Devs CLI
npm install -g @serverless-devs/s
# Configure your Alibaba Cloud credentials
s config add
# Compile the Deno application
deno compile --allow-net --allow-read --allow-env \
--output aliyun/xmcl-api \
index.ts
# Deploy the function
s deploy --use-local -y
```
The deployment uses a compiled Deno binary and automatically deploys from the main branch via GitHub Actions.
**Required Secrets for GitHub Actions:**
- `ALIYUN_ACCOUNT_ID` - Alibaba Cloud Account ID
- `ALIYUN_ACCESS_KEY_ID` - Alibaba Cloud Access Key ID
- `ALIYUN_ACCESS_KEY_SECRET` - Alibaba Cloud Access Key Secret
- Environment variables (same as Primary Service)
### Custom Server (China)
For the China service, deploy to a suitable hosting provider with Go support:
```bash
go build -o server main.go
# Then deploy the binary to your server
```
## TURN Server
For WebRTC functionality, a COTURN server is used. Configuration details are in `COTURN.md`.
## License
This project is licensed under the MIT License - see the LICENSE file for details.