mcO2switch (package NPM : mco2switch)

mcO2switch est le nom de marque du projet. NPM impose les noms de packages en minuscules : le nom publiable est donc mco2switch, et la commande réelle est npm install mco2switch. Un package NPM nommé exactement mcO2switch ne peut pas être publié avec cette casse.

Projet expérimental Node.js pour mesurer les capacités réellement accessibles depuis une application cPanel/o2switch et, si elles sont autorisées, piloter un petit programme Java ou un serveur Minecraft Java.

Important : ce projet ne contourne aucune restriction. Il ne peut pas garantir qu’un processus Java restera vivant sur un hébergement mutualisé. Seule l’observation de npm run diagnose puis un test contrôlé permet de conclure pour votre compte.

Ce que le projet fait

• application Node.js HTTP compatible avec PORT, Passenger et cPanel Node.js Application ;
• diagnostic Node, java -version, création de processus, processus vivant environ une seconde, mémoire visible, écriture et variables d’environnement ;
• JavaRunner avec JAR local, arguments JVM/programme, stdout/stderr, logs, arrêt SIGTERM puis SIGKILL si nécessaire et redémarrage limité explicitement ;
• interface web minimale : état, démarrage, arrêt, logs, diagnostic et test de base de données ;
• stockage utilisateur (data/logs, data/reports, data/backups, data/configs, data/downloads) ;
• couche MySQL/MariaDB optionnelle via pool, activée seulement avec des variables complètes ;
• alternative utile lorsque Java est indisponible : panel/API, stockage, rapports, configuration et relais vers un serveur externe à implémenter côté intégration.

Limites assumées

Node.js peut appeler child_process si l’hébergeur l’autorise, mais cela ne signifie pas que Java est installé, que les JAR sont acceptés, ni qu’un processus peut fonctionner indéfiniment. CloudLinux/Passenger peut imposer CPU, RAM, durée, nombre de processus et redémarrages. Ces limites ne sont pas toutes exposées à Node et o2switch peut faire évoluer sa politique. Un résultat works est donc un résultat de test, jamais une promesse de serveur Minecraft 24/7.

Le panel ne télécharge ni n’exécute automatiquement un JAR distant. Déposez manuellement un JAR de confiance dans server/server.jar, avec respect des licences et conditions de distribution de Minecraft/Paper/Purpur. Commencez par KeepAlive ou un JAR minuscule, pas par un serveur Minecraft.

Utilisation après publication NPM

Installation dans un dossier d’application :

npm install mco2switch
cp node_modules/mco2switch/.env.example .env
npx mco2switch-diagnose
npx mco2switch
npx mco2switch-run --help
npx mco2switch-o2switch --help

Ou dans package.json de l’application :

{
  "scripts": {
    "start": "mco2switch",
    "diagnose": "mco2switch-diagnose"
  }
}

Le package exporte aussi une API JavaScript :

import { startServer, createApp } from 'mco2switch';

// Pour cPanel/Passenger, le binaire `mco2switch` suffit généralement.
// Pour une intégration personnalisée :
const { app } = createApp({ port: 3000 });
app.listen(3000);

Les données (data/, server/) sont volontairement créées dans le dossier courant de l’application, pas dans node_modules. Les fichiers statiques sont servis depuis le package installé.

Installation locale et cPanel

# développement depuis le dépôt
npm install
cp .env.example .env
npm run check
npm test
npm run diagnose
npm start

Sur cPanel :

1. Téléverser le projet dans un dossier du compte, hors public_html si possible.
2. Ouvrir Software > Setup Node.js App (le nom exact peut varier selon l’interface).
3. Choisir une version Node compatible avec engines, le mode production, le dossier de l’application et node_modules/mco2switch/src/server.js comme fichier de démarrage si cPanel exige un fichier. Lorsque le champ accepte une commande, utiliser mco2switch. Le nom de l’application/Passenger peut être demandé par cPanel.
4. Exécuter npm install depuis le bouton cPanel ou le terminal du compte. Ne pas utiliser sudo.
5. Définir PORT selon la valeur injectée par cPanel/Passenger. Ne pas réserver de port fixe ni lancer un serveur avec systemd.
6. Définir DATA_DIR vers un dossier inscriptible du compte et les variables JAVA_* si vous testez Java. PANEL_TOKEN est recommandé avant toute exposition publique.
7. Redémarrer l’application depuis cPanel puis consulter / et /api/health.

Le serveur écoute APP_HOST (par défaut 0.0.0.0) et PORT. Il n’a besoin ni de Docker, ni de root, ni de systemd, ni de sudo, ni d’interface graphique.

Diagnostic

npm run diagnose

Le JSON est affiché et sauvegardé dans data/reports/diagnostic-*.json.

• works : le test précis a réussi dans les conditions du test ;
• unavailable : commande, variable ou service non disponible ;
• blocked : refus, erreur ou délai dépassé ; cela peut venir de l’environnement ;
• configuration : décision dépendant de cPanel/o2switch, non déductible par Node.

Interprétation pratique :

1. java=unavailable : installer/activer Java via les outils autorisés de l’hébergement ou abandonner l’exécution locale ; ne pas tenter de contourner.
2. childProcess=blocked : JavaRunner ne peut pas fonctionner ; utilisez le mode panel/API.
3. persistentProcess=works : seulement un test d’environ une seconde ; lancez ensuite un JAR de test de quelques secondes.
4. memory est informatif : la mémoire visible par Node n’est pas nécessairement la limite CloudLinux.
5. storage=blocked : corriger DATA_DIR et les permissions via cPanel, sans permissions dangereuses.

Lancer un serveur local ou un fichier BAT

Pour lancer le fichier BAT de ton serveur Minecraft sous Windows, installe le package dans le dossier du serveur puis utilise :

npm install mco2switch
npx mco2switch-run --script "C:\Users\shros\Documents\Eternal Legacy\start.bat"

Remplace start.bat par le nom réel de ton fichier. Le chemin peut contenir des espaces s’il est entre guillemets. Cette commande reste attachée au terminal et affiche les sorties du script. Fermer le terminal arrêtera généralement le serveur : c’est le comportement normal d’un processus attaché.

Pour lancer directement un JAR Java :

npx mco2switch-run --jar "C:\Users\shros\Documents\Eternal Legacy\server.jar" --jvm-arg "-Xmx2G" --arg nogui

Un fichier .bat est un script Windows et ne peut pas être envoyé tel quel sur o2switch, qui utilise Linux. Sur o2switch, crée un équivalent start.sh, par exemple :

#!/bin/sh
exec java -Xms512M -Xmx1G -jar server.jar nogui

Puis rends-le exécutable depuis le terminal cPanel si nécessaire (chmod u+x start.sh) et lance-le avec la commande dédiée :

npx mco2switch-o2switch start --script ./start.sh
npx mco2switch-o2switch status
npx mco2switch-o2switch stop

Cette commande détache le processus du terminal (detached/unref) et écrit son PID dans data/server.pid. Elle permet normalement de fermer la page ou la session SSH sans envoyer immédiatement le signal de fermeture au processus. Elle ne contourne pas les limites o2switch/CloudLinux/Passenger : l’hébergeur peut tout de même terminer un processus persistant, limiter sa mémoire/CPU ou interdire ce type d’usage. Le diagnostic du compte reste obligatoire.

Pour un JAR directement sur o2switch :

npx mco2switch-o2switch start --jar ./server/server.jar --jvm-arg "-Xmx1G" --arg nogui

Ne lance qu’une seule instance. Utilise status pour vérifier le PID et stop pour l’arrêt propre. Aucun sudo, Docker ou systemd n’est requis.

Test Java contrôlé

Si javac est disponible localement (il n’est pas requis par l’application) :

mkdir -p server
javac -d /tmp/o2panel-java fixtures/KeepAlive.java
jar --create --file server/server.jar --main-class KeepAlive -C /tmp/o2panel-java KeepAlive.class
JAVA_JVM_ARGS='-DdurationMs=5000' npm start

Puis utiliser Démarrer dans le panel, observer les logs et arrêter. Sur un compte distant, compiler ailleurs avec une version Java compatible et transférer seulement ce petit JAR de test. Si le processus disparaît avant cinq secondes, notez le diagnostic et les logs : c’est un signal d’incompatibilité ou de limite, pas une invitation à contourner l’hébergeur.

Minecraft (seulement après le test)

Copier le JAR légalement obtenu dans server/server.jar, configurer par exemple JAVA_JVM_ARGS=-Xms512M -Xmx1G selon la mémoire réellement allouée, et démarrer sans auto-restart au premier essai. Paper, Purpur, Vanilla et NeoForge ont des exigences propres (version Java, mémoire, fichiers, acceptation EULA, durée CPU). Le projet ne prétend pas qu’ils sont supportés sur o2switch : le diagnostic et le test réel de votre compte sont la source de vérité. Ne lancez pas plusieurs instances.

Mode alternatif sans Java

L’application reste déployable sans Java. Elle fournit une API de santé, diagnostic, logs, stockage et statut. La couche MySQL peut stocker des événements/configurations après ajout d’un appel métier. Un relais vers un serveur Minecraft externe peut être ajouté via une API authentifiée et HTTPS ; ce dépôt ne fabrique pas un faux serveur Minecraft et ne promet pas un accès réseau sortant qui serait bloqué.

Endpoints : GET /api/health, /api/status, /api/logs, /api/storage, /api/diagnostic, /api/database, POST /api/start, POST /api/stop, POST /api/command. Si PANEL_TOKEN est défini, utiliser Authorization: Bearer <token> ou X-Panel-Token pour tous les endpoints hors santé. Ne pas exposer le panel sans authentification/proxy HTTPS.

Base MySQL/MariaDB

Renseigner DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_POOL_SIZE dans les variables cPanel, jamais dans Git. GET /api/database teste la connexion. La méthode migrate() crée uniquement panel_events et peut être appelée depuis une future commande d’administration ; aucune migration destructive n’est lancée automatiquement.

Dépannage et sécurité

• EACCES : dossier appartenant au compte et accessible en écriture ; corriger depuis cPanel.
• ENOENT : vérifier JAVA_PATH et le chemin absolu/résolu de JAVA_JAR_PATH.
• arrêt automatique : conserver le rapport, réduire le test et consulter les limites/conditions o2switch ; ne pas multiplier les redémarrages.
• logs : data/logs/application.log, rapports : data/reports/ ; protéger ces dossiers et exclure .env, mots de passe et JAR privés du contrôle de version.
• cette application est un prototype d’administration : ajouter HTTPS, authentification forte, CSRF et audit avant usage public.

Structure

src/app.js                    API publique createApp/startServer
src/server.js                 HTTP + API + Passenger
src/cli/start.js              commande `mco2switch`
src/cli/run.js                lancement attaché BAT/SH/JAR
src/cli/o2switch.js           lancement Linux détaché + PID
src/server-runner.js          runner générique de serveur
src/java-runner.js            cycle de vie d’un JAR
src/diagnostics/environment.js tests factuels de l’environnement
src/db.js                     MySQL/MariaDB optionnel
src/storage.js, logger.js      données et logs
public/index.html              interface sans build
fixtures/KeepAlive.java       test Java contrôlé
test/                         tests Node intégrés