{"id":20169008,"url":"https://github.com/mage/mage-module-maintenance","last_synced_at":"2025-06-15T11:06:46.640Z","repository":{"id":82165220,"uuid":"95089520","full_name":"mage/mage-module-maintenance","owner":"mage","description":"Module to help you implement a maintenance mode for your game cluster","archived":false,"fork":false,"pushed_at":"2017-07-21T11:45:11.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-10T04:57:23.783Z","etag":null,"topics":["mage","maintenance-mode","module"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mage.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-22T07:53:33.000Z","updated_at":"2017-06-28T23:29:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"7853726f-d2c2-4638-a2ec-66130a97de2e","html_url":"https://github.com/mage/mage-module-maintenance","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mage/mage-module-maintenance","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mage%2Fmage-module-maintenance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mage%2Fmage-module-maintenance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mage%2Fmage-module-maintenance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mage%2Fmage-module-maintenance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mage","download_url":"https://codeload.github.com/mage/mage-module-maintenance/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mage%2Fmage-module-maintenance/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259964327,"owners_count":22938724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mage","maintenance-mode","module"],"created_at":"2024-11-14T01:11:04.291Z","updated_at":"2025-06-15T11:06:46.623Z","avatar_url":"https://github.com/mage.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"mage-module-maintenance\n=======================\n\nModule to help you implement a maintenance mode for your game cluster.\n\nThis module will help you deal with the following tasks:\n\n  1. Starting and stopping a maintenance\n  2. Broadcasting maintenance status messages on start and stop\n  3. Customizing the behaviour of your user commands during maintenance\n  4. Implementing drain systems to allow current matches to complete\n     while disallowing the creationg of new matches\n\nInstallation\n-------------\n\n```shell\nnpm install --save mage-module-maintenance\n```\n\nUsage\n-----\n\n### Module creation\n\n\u003e lib/modules/maintenance/index.ts\n\n```typescript\nimport maintenance, {\n  AbstractMaintenanceModule\n} from 'mage-module-maintenance'\n\nclass MaintenanceModule extends AbstractMaintenanceModule {\n   // Store the maintenance message\n   public async store(message: maintenance.IMessage) {\n　　　　\n   }\n\n   // Load the maintenance status from persistent storage\n   public async load() {\n\n   }\n}\n\nexport default new MaintenanceModule()\n```\n\nThen, create the following user commands:\n\n  * start\n  * end\n  * status\n\n\u003e lib/modules/maintenance/usercommands/start.ts\n\n```typescript\n// mage\nimport * as mage from 'mage'\nimport MaintenanceModule from '../'\n\n// validation tools\nimport { Acl } from 'mage-validator'\n\n// User command\nexport default class {\n  @Acl('*')  // You might want to customise this to your need!\n  public static async execute(_state: mage.core.IState) {\n    return MaintenanceModule.start() // create the same user command for end and status!\n  }\n}\n```\n\n### On the client side\n\nDepending on your client SDK, the behavior may be slightly different. However, you may expect the following\nthings to happen:\n\n  1. When calling a user command, you will receive a 'maintenance' error automatically to all user commands\n  2. Through [Message Stream](https://mage.github.io/mage/api.html#message-stream), you will receive:\n    * **maintenance.start**: With a JSON message containing details about the maintenance\n    * **maintenance.end**: With a JSON message containing additional details\n\n### User commands decoration\n\nYou may want to allow certain user commands to be called during a maintenance;\nfor instance, you may want to allow users to complete their current match, then\nkeep track of the number of active match in your admin dashboard and wait until\nthe count goes to zero before starting your actual maintenance process.\n\n\u003e lib/modules/match/usercommands/someAction.js\n\n```javascript\nconst { OnMaintenance, AllowAccess } from '../../maintenance'\n\nOnMaintenance(AllowAccess)(exports)\n\nexports.acl = ['*']\n\nexports.execute = async function (state) {\n  // your command code\n}\n```\n\n\u003e lib/modules/match/usercommands/someAction.ts\n\n```typescript\nimport * as mage from 'mage'\nimport { OnMaintenance, AllowAccess } from '../../maintenance'\n\n// validation tools\nimport { Acl } from 'mage-validator'\n\n// User command\nexport default class {\n  @Acl('*')\n  @OnMaintenance(AllowAccess)\n  public static async execute(state: mage.core.IState) {\n    // your command code\n  }\n}\n```\n\n### Per-user access allowance\n\nDuring your maintenance, you will likely want to allow select \nplayers to access the game (normally, members of your development team).\n\n\u003e lib/modules/players/usercommands/login.ts\n\n```typescript\n// mage\nimport * as mage from 'mage'\nimport { OnMaintenance, AllowAccess, AllowUser, DenyUser } from '../../maintenance'\n\n// validation tools\nimport { Acl } from 'mage-validator'\n\n// User command\nexport default class {\n  @Acl('*')\n  @OnMaintenance(AllowAccess)\n  public static async execute(state: mage.core.IState) {\n    // your login code, then\n\n    if (player.hasMaintenanceAccess) {\n      AllowUser(state)\n      return player\n    }\n    \n    DenyUser(state)\n  }\n}\n```\n\nYou may choose to selectively allow access per user, per user\ncommand; you can also whitelist a user by calling the `AllowUser`\nfunction.\n\nLicense\n-------\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmage%2Fmage-module-maintenance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmage%2Fmage-module-maintenance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmage%2Fmage-module-maintenance/lists"}