requirements.md
1 <!-- 2 SPDX-FileCopyrightText: 2025 Lazerbeak12345 on Github and contributors 3 4 SPDX-License-Identifier: MIT 5 --> 6 7 # Development Requirements for Luanti LuaRocks Wrapper 8 9 > The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 10 > NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 11 > "OPTIONAL" in this document are to be interpreted as described in 12 > RFC 2119 and RFC 8174. 13 14 ## Purpose of this document 15 16 Ths purpose of this document is to describe, clearly, what this project intends to do. 17 18 As made clear above, we'll be using RFC's 2119 and 8174 in this document. 19 20 ## Requirements 21 22 ### Mod Requirements 23 24 1. This mod MUST provide an API to register and load Luarocks libraries, so long as they are packaged with the dependant developer's code appropriatly. 25 2. This mod MUST NOT require use of `secure.trusted_mods` 26 3. This mod MUST implement a custom environment that includes an accurate and secure `require` function. 27 4. This mod MUST prevent security exploits. 28 5. This mod MAY provide an opt-in method for server administrators and singleplayers to use `secure.trusted_mods` to improve performance of these libraries at potential cost to security. If this is done we MUST inform users of the inherent risks. 29 6. Documentation MUST be provided. 30 7. Comprehensive unit testing SHOULD be developed. 31 8. Mod MUST recreate the insecure environment as close as is possible for the LuaRock, especially the `require` function, which internally behaves differently. More details will be provided in the design documents. 32 9. Mod MUST be forward compatible. 33 10. Mod MAY be backward compatible. 34 11. Backward incompatibilities MUST be tracked with semver. 35 12. Mod MUST provide APIs to provide a single (1) LuaRocks package as a single Luanti package. 36 13. Mod MUST provide ways for the code in the Luanti package to provide a lmited form of the wrapped rock. 37 38 ### Tooling Requirements 39 40 1. This tooling MAY provide a way to manage and update LuaRocks dependencies. 41 2. Documentation MUST be provided. 42 3. Comprehensive unit testing SHOULD be developed. 43 4. Tooling MUST be forward compatible. 44 5. Tooling MAY be backword compatible. 45 6. Backword incompatibilities MUST be tracked with semver. 46 47 ## User stories 48 49 <!-- 50 - As a **mod developer** I want to **** so that ****. 51 - As a **Server Admin** I want to **** so that ****. 52 - As a **luarocks developer** I want to **** so that ****. 53 - As a **player** I want to **** so that ****. 54 --> 55 56 - As a **luarocks developer** I want to **rely on an environment resembling luajit** so that **I need less luanti code**. 57 - As a **luarocks developer** I want to **use the require function** so that **I need less luanti code**. 58 - As a **mod developer** I want to **register a LuaRocks library** so that **the library is available for use in luanti**. 59 - As a **mod developer** I want to **read the docs** so that **I can make a mod**. 60 - As a **mod developer** I want to **look at unit tests** so that **I have tested examples**. 61 - As a **mod developer** I want to **cherry pick the rock API** so that **only secure things can be done**. 62 - As a **mod developer** I want to **update the wrapped rock** so that **the latest features and security patches are available**. 63 - As a **Server Admin** I want to **use this mod** so that **I don't need trusted_mods**. 64 - As a **Server Admin** I want to **be able to trust a wrapped rock** so that **I can improve performance at cost of security**. 65 - As a **Server Admin** I want to **look at unit tests** so that **I know the mod works**. 66 - As a **Server Admin** I want to **rely on environment resembling luajit** so that **the server is secure**. 67 - As a **Server Admin** I want to **see semver versions** so that **I understand how and when to upgrade the server**. 68 - As a **Server Admin** I want to **see a 1:1 mod:rock relationship** so that **I know what's installed, and have less duplicate code**. 69 - As a **Server Admin** I want to **have cherrypicked rock APIS** so that **insecure things won't crash the server**. 70 - As a **player** I want to **use any luanti client** so that **I can play the game**. 71 72 ## Use-cases 73 74 ```mermaid 75 flowchart LR 76 subgraph actors 77 RockDev[LuaRock developer] 78 ModDev[mod developer] 79 Admin[Server Admin] 80 Player[Player] 81 end 82 subgraph Luanti Mod 83 RegLib((Register Luarock lib)) 84 subgraph docs 85 LookAtDocs((Look at docs)) 86 end 87 subgraph tests 88 LookAtTests((Look at unit tests)) 89 TestedExamples((Look at tested examples)) 90 end 91 subgraph provided api 92 CherryPickAPI((specify)) 93 RelyCherryPickAPI((rely on)) 94 end 95 96 Use((Use)) 97 Trust((mark mod as trusted)) 98 subgraph environment 99 FN((use functions)) 100 end 101 subgraph semver 102 UseSemver((use semver versions)) 103 end 104 OneModOneRock((rely on 1:1 mod:rock)) 105 end 106 subgraph Rock 107 UpdateRock((ensure rock is updated)) 108 end 109 subgraph LuantiServer 110 UpgradeServer[upgrade server] 111 UnderstandServer[understand the server] 112 end 113 subgraph Luanti Client 114 UseLuantiClient((use)) 115 end 116 subgraph goals 117 LatestFeatures[game on latest features] 118 Secure[server is secure] 119 NoCrash[server does not crash] 120 LessLuanti[Less luanti code in rock] 121 Avail[rock is available in luanti] 122 MakeMod[Can make a mod] 123 KnowModWorks[Know that the mod works] 124 NoTrust[no trusted_mods needed] 125 SpeedForSafety[Faster at cost of safety] 126 PlayGame[can play game] 127 end 128 129 RockDev --> FN --> LessLuanti 130 131 ModDev --> RegLib --> Avail 132 ModDev --> LookAtDocs --> MakeMod 133 ModDev --> LookAtTests -.-> TestedExamples --> MakeMod 134 ModDev --> CherryPickAPI --> Secure 135 ModDev --> UpdateRock --> Secure 136 UpdateRock --> LatestFeatures 137 138 Admin --> Use --> NoTrust 139 Admin --> Trust --> SpeedForSafety 140 Admin --> LookAtTests --> KnowModWorks 141 Admin --> FN --> Secure 142 Admin --> UseSemver -.-> UpgradeServer --> Secure 143 Admin --> OneModOneRock -.-> UnderstandServer --> Secure 144 Admin --> RelyCherryPickAPI --> NoCrash 145 RelyCherryPickAPI --> Secure 146 147 Player --> UseLuantiClient --> PlayGame 148 ```