refactor - plugins dispatchers, timers, http

Buildstruct/bsa-platform-gmod@34cd853

Author: blueshank-gh

docs/platforms/garrysmod/modules/plugins/reference.md

@@ -5,60 +5,149 @@ For a practical authoring guide, see [Creating a Plugin](creating.md).
 
 ## Manager API
 
-- `#!ts plugins:add(name: string, struct: table): plugin.class`  
+- `#!ts plugins:add(name: string, struct: table): plugin.class`\
   Registers a plugin definition, creates `config.Plugins.<name>`, and returns the registered plugin class.
 
-- `#!ts plugins:enable(name: string): boolean, ...`  
+- `#!ts plugins:enable(name: string): boolean, ...`\
   Enables a registered plugin if it is not already active.
 
-- `#!ts plugins:disable(name: string): boolean, ...`  
+- `#!ts plugins:disable(name: string): boolean, ...`\
   Disables an active plugin instance.
 
-- `#!ts plugins:remove(name: string): boolean, ...`  
+- `#!ts plugins:remove(name: string): boolean, ...`\
   Disables the plugin if needed and removes it from the registry.
 
-- `#!ts plugins:get(name: string): plugin.class | false`  
+- `#!ts plugins:get(name: string): plugin.class | false`\
   Returns the registered plugin class.
 
-- `#!ts plugins:list(): table`  
+- `#!ts plugins:list(): table`\
   Returns the registry table.
 
 ## Base Plugin Methods
 
 Every registered plugin inherits from the base `plugin` class.
 
-- `#!ts plugin:constructor()`  
+- `#!ts plugin:constructor()`\
   Called when the plugin is enabled.
 
-- `#!ts plugin:destructor()`  
+- `#!ts plugin:destructor()`\
   Called when the plugin is disabled.
 
-- `#!ts plugin:active(): boolean`  
+- `#!ts plugin:active(): boolean`\
   Returns whether the plugin instance is active.
 
-- `#!ts plugin:disable()`  
-  Shortcut for `plugins:disable(self.name)`.
+- `#!ts plugin:disable()`\
+  Shortcut for `#!ts plugins:disable(self.name)`.
 
-- `#!ts plugin:enable()`  
-  Shortcut for `plugins:enable(self.name)`.
+- `#!ts plugin:enable()`\
+  Shortcut for `#!ts plugins:enable(self.name)`.
 
-- `#!ts plugin:remove()`  
-  Shortcut for `plugins:remove(self.name)`.
+- `#!ts plugin:remove()`\
+  Shortcut for `#!ts plugins:remove(self.name)`.
 
-- `#!ts plugin:transport(): table`  
+- `#!ts plugin:transport(): table`\
   Returns transport-safe plugin information.
 
-- `#!ts plugin:add_hook(name: string, id: string, callback: function)`  
+### Dispatcher Tracking
+
+- `#!ts plugin:create_dispatcher(name: string): dispatcher.object`\
+  Creates a new dispatcher object.
+
+- `#!ts plugin:add_dispatcher(handle: dispatcher, callback: function, id?: string): dispatcher.handle`\
+  Connects a callback to a dispatcher and tracks the `dispatcher.handle` for automatic cleanup. Uses `<plugin>.<id>` as the identity.
+
+- `#!ts plugin:remove_dispatcher(handle: dispatcher, id?: string): boolean`\
+  Disconnects a tracked dispatcher handle.
+
+- `#!ts plugin:clear_dispatchers()`\
+  Disconnects all tracked dispatcher connections for the plugin instance.
+
+### Hook Tracking
+
+- `#!ts plugin:add_hook(name: string, id: string, callback: function)`\
   Adds a tracked hook using `<plugin>.<id>` as the final hook ID.
 
-- `#!ts plugin:remove_hook(name: string, id: string)`  
+- `#!ts plugin:remove_hook(name: string, id: string)`\
   Removes one tracked hook.
 
-- `#!ts plugin:clear_hooks()`  
+- `#!ts plugin:clear_hooks()`\
   Removes all tracked hooks for the plugin instance.
 
-- `#!ts plugin:clean()`  
-  Runs cleanup logic. Currently this clears tracked hooks.
+### Timer Tracking
+
+- `#!ts plugin:simple_timer(delay: number, callback: function)`\
+  Creates a one-shot timer with an auto-generated identity. Automatically unregisters after firing.
+
+- `#!ts plugin:add_timer(id: string, delay: number, reps: number, callback: function)`\
+  Creates a tracked timer using `<plugin>.<id>` as the identity. Use `0` reps for infinite repetition.
+
+- `#!ts plugin:exist_timer(id: string): boolean`\
+  Returns whether a tracked timer exists.
+
+- `#!ts plugin:toggle_timer(id: string): boolean`\
+  Toggles a tracked timer between paused and running.
+
+- `#!ts plugin:pause_timer(id: string): boolean`\
+  Pauses a tracked timer.
+
+- `#!ts plugin:unpause_timer(id: string): boolean`\
+  Unpauses a tracked timer.
+
+- `#!ts plugin:repsleft_timer(id: string): number`\
+  Returns remaining repetitions for a tracked timer.
+
+- `#!ts plugin:timeleft_timer(id: string): number`\
+  Returns remaining time until the next tick of a tracked timer.
+
+- `#!ts plugin:adjust_timer(id: string, delay: number, reps?: number, callback?: function)`\
+  Adjusts the delay, repetitions, or callback of an existing tracked timer.
+
+- `#!ts plugin:stop_timer(id: string)`\
+  Stops a tracked timer.
+
+- `#!ts plugin:start_timer(id: string)`\
+  Starts a stopped tracked timer.
+
+- `#!ts plugin:remove_timer(id: string)`\
+  Removes a tracked timer. Also aliased as `destroy_timer`.
+
+- `#!ts plugin:clear_timers()`\
+  Removes all tracked timers for the plugin instance.
+
+!!! note
+    `create_timer` is an alias for `add_timer`.\
+    `destroy_timer` is an alias for `remove_timer`.
+
+### HTTP Tracking
+
+- `#!ts plugin:http(url: string, callback: function, options?: table): request`\
+  Performs an HTTP request with automatic retry support.\
+  Returns a request handle that can be cancelled.\
+  The callback receives `(code, body, headers)` on success or `(false, reason)` on failure.\
+  Requests are automatically ignored if the plugin becomes inactive.
+
+    **Options table:**
+
+    | Field        | Type     | Default | Description                    |
+    |-------------|----------|---------|--------------------------------|
+    | `retry`     | `number` | `1`     | Number of retry attempts       |
+    | `method`    | `string` | `"GET"` | HTTP method                    |
+    | `body`      | `string` | `nil`   | Request body                   |
+    | `type`      | `string` | `nil`   | Content type                   |
+    | `timeout`   | `number` | `nil`   | Request timeout                |
+    | `headers`   | `table`  | `{}`    | Request headers                |
+    | `parameters`| `table`  | `{}`    | URL query parameters           |
+
+- `#!ts plugin:cancel_http(request: table)`\
+  Cancels a tracked HTTP request so its callback will not fire.
+
+- `#!ts plugin:clear_https()`\
+  Cancels all tracked HTTP requests for the plugin instance.
+
+### Cleanup
+
+- `#!ts plugin:clean()`\
+  Runs full cleanup: clears tracked dispatchers, hooks, timers, and HTTP requests.
 
 ## Loader Behavior
 
@@ -108,19 +197,14 @@ Failure behavior:
 When `plugins:disable(name)` runs, the runtime:
 
 1. Calls `plugin:destructor()`.
-2. Calls `plugin:clean()` which clears tracked hooks.
+2. Calls `plugin:clean()` which clears tracked dispatchers, hooks, timers, and HTTP requests.
 3. Removes the client interface if one was mounted.
 4. Removes the runtime client/language config containers for that plugin.
 5. Removes dynamic child nodes created under `self.config`.
 6. Clears the active registry entries.
 7. Syncs the new active plugin list.
 8. Invokes `plugins.disabled(plugin, state, err)`.
 
-Important detail:
-
-- Hook cleanup is automatic if you used `self:add_hook(...)`.
-- Timers are not tracked by the plugin system yet.
-
 ## Runtime Events
 
 These dispatchers live on `plugins`: