{"id":"zenukopublic/netguard","name":"netguard","scope":"zenukopublic","platform":"roblox","description":"A declarative, type-safe, rate-limiting networking framework for Roblox with automatic UnreliableRemoteEvent support.","version":"1.0.0","latest":"1.0.0","versions":["1.0.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"2e552d8174adba28a6a1f19bc6897bb2869a62ce07f5c48e39b2e486766a8e5c","likes":0,"downloads":0,"install":"forest install zenukopublic/netguard","url":"https://forest.dev/p/roblox/zenukopublic/netguard","files":"https://api.forest.dev/ai/package/roblox/zenukopublic/netguard/files","readme":"# `netguard`\n\n> **A declarative, type-safe, rate-limiting networking framework for Roblox with automatic `UnreliableRemoteEvent` support.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Language: Luau](https://img.shields.io/badge/Language-Luau-blue.svg)](https://luau-lang.org/)\n[![Wally: Available](https://img.shields.io/badge/Wally-Available-brightgreen.svg)](https://wally.run/)\n\n---\n\n> **Production Origin:** This package was extracted and generalized from infrastructure developed for **Kabbrawl**, a private competitive multiplayer Roblox experience. Kabbrawl itself remains proprietary; this package contains only reusable infrastructure and no proprietary assets or game-specific content.\n\n---\n## 🛡️ Why NetGuard?\n\nIn competitive and commercial Roblox games, the majority of client-server vulnerabilities come from:\n1. **Remote Flooding & DoS:** Exploiters spamming remotes 500 times/second to crash server loops.\n2. **Type Confusion & Malformed Payloads:** Sending unexpected types (`nil`, `string` instead of `number`) that trigger unhandled server errors.\n3. **No Protocol Discipline:** Scattering raw `RemoteEvent` instances throughout `ReplicatedStorage` with inconsistent naming and no rate-limit guarantees.\n4. **Under-utilization of UDP:** Failing to use `UnreliableRemoteEvent` for high-frequency position or visual state updates.\n\n**NetGuard** solves all four issues with a single declarative API.\n\n---\n\n## ✨ Features\n\n* **Declarative Schemas:** Define your networking contract in one central module.\n* **Automatic Remote Management:** Automatically instantiates and pools `RemoteEvent` (reliable/ordered) and `UnreliableRemoteEvent` (unreliable/fast) based on your config.\n* **Built-in Server Rate Limiting:** Per-player, per-packet token-bucket rate limiting rejects remote spam before it reaches your game logic.\n* **Recursive Payload Type-Checking:** Primitives, nested tables, `Vector3`, `CFrame`, `Instance`, and `Color3`.\n* **Stateful Predicate Guards:** Attach context checks (e.g. `isNotBenched`, `hasSufficientStamina`) that verify game state before invoking listeners.\n* **Rejection Telemetry:** Capture security anomalies and exploit attempts with clean `onRejected` callbacks.\n\n---\n\n## 🚀 Installation\n\n### Via Wally\nAdd `netguard` to your `wally.toml`:\n\n```toml\n[dependencies]\nNetGuard = \"zenukopublic/netguard@1.0.0\"\n```\n\n---\n\n## 📖 Quickstart\n\n### 1. Define Your Packet Registry (`Shared/Packets.luau`)\n\n```luau\nlocal NetGuard = require(Packages.NetGuard)\n\nlocal net = NetGuard.new()\n\nnet:registerAll({\n    -- High-frequency state sync (uses UnreliableRemoteEvent / UDP)\n    PlayerSync = {\n        direction = \"ClientToServer\",\n        reliable = false,\n        cooldown = 1 / 30, -- Capped at 30 Hz\n        schema = {\n            cframe = \"CFrame\",\n            velocity = \"Vector3\",\n        },\n    },\n\n    -- Critical action (uses standard RemoteEvent / TCP)\n    PerformAction = {\n        direction = \"ClientToServer\",\n        reliable = true,\n        cooldown = 0.5, -- Max 2 actions per second\n        predicates = { \"isAlive\", \"hasStamina\" },\n        schema = {\n            actionType = \"string\",\n            targetId = \"number\",\n        },\n    },\n})\n\nreturn net\n```\n\n### 2. Server Implementation (`Server/CombatHandler.luau`)\n\n```luau\nlocal net = require(ReplicatedStorage.Shared.Packets)\n\nnet:bindServer(\"PerformAction\", function(player, payload)\n    print(player.Name, \"performed\", payload.actionType, \"on\", payload.targetId)\nend, {\n    getContext = function(player, payload)\n        return {\n            isAlive = player.Character ~= nil,\n            hasStamina = true, -- Check your game's stamina component\n        }\n    end,\n    onRejected = function(player, reason, payload)\n        warn(`[SECURITY] Rejected {player.Name}: {reason}`)\n    end,\n})\n```\n\n### 3. Client Implementation (`Client/InputController.luau`)\n\n```luau\nlocal net = require(ReplicatedStorage.Shared.Packets)\n\n-- Send an action\nlocal ok, err = net:fireServer(\"PerformAction\", {\n    actionType = \"Tackle\",\n    targetId = 12345,\n})\n\nif not ok then\n    warn(\"Failed to fire action:\", err)\nend\n```\n\n---\n\n## 🧪 Testing\n\nRun core unit tests headlessly with [Lune](https://github.com/lune-org/lune):\n```bash\nlune run tests/netguard.test.luau\n```\n\n---\n\n## 📄 License\n\nMIT License. Free for personal and commercial use.\n","readmeTruncated":false}