feat: hook api #188

twisti-dev · 2026-01-24T22:09:42Z

This pull request introduces a new modular hook system for the Surf API, enabling plugins to declare and manage dependencies on classes and other plugins, and providing a lifecycle for hooks. The changes include the addition of hook metadata annotations, hook requirement annotations, a core hook API, a base AbstractHook class, and the backend services for hook discovery and management. The plugin test and server modules are updated to use this new system.

Core Hook System Implementation:

Introduced AbstractHook base class, which manages hook lifecycle (bootstrap, load, enable, disable) and enforces the presence of HookMeta annotation. Hooks are now comparable by priority.
Added HookMeta annotation for hooks, allowing specification of hook priority.
Implemented requirement annotations: DependsOnClass, DependsOnClassName, DependsOnPlugin, and DependsOnOnePlugin, enabling hooks to declare dependencies on classes or plugins. [1] [2] [3] [4]
Added SurfHookApi interface and singleton accessor for managing hook lifecycle and querying hooks by type or owner.
Implemented HookService abstract class, providing hook discovery, dependency checks, and lifecycle management, with support for caching and logging missing dependencies.

Bukkit/Server Integration:

Added PaperHookService implementation to integrate the hook system with Bukkit/Paper servers, handling plugin resource loading, classloader access, plugin presence checks, and logging.
Introduced JavaPluginProxy interface and integrated it into the server reflection utilities for classloader access. [1] [2]
Updated the test plugin (BukkitPluginMain) to use the new async lifecycle methods and call the hook API at appropriate stages.

Example Hook and Usage:

Added a sample TestHook class demonstrating the use of the new hook system, including requirement annotations and lifecycle logging.

Other Improvements and Fixes:

Improved reflection proxy handling in Java by using MethodHandles.privateLookupIn for better encapsulation and compatibility, and updated method finding logic. [1] [2] [3] [4] [5] [6]
Minor fix in EntityGlowingData to access TeamData companion object correctly.

These changes collectively introduce a robust, extensible hook system, improving modularity and dependency management for plugins in the Surf API ecosystem.

…rations for Bukkit, Velocity, and core APIs

github-actions · 2026-01-24T22:11:40Z

⚠️ API/ABI changes detected!

This PR contains changes that modified the public API. To update the reference ABI dumps:

./gradlew updateLegacyAbi
git add **/api/**
git commit -m "Update ABI reference"
git push

After updating, the CI will pass. Make sure the changes are backward compatible.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a1112ea2a0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

...rf-api-processor/src/main/kotlin/dev/slne/surf/surfapi/processor/hook/HookSymbolProcessor.kt

...ity-server/src/main/kotlin/dev/slne/surf/surfapi/velocity/server/hook/VelocityHookService.kt

…trieval

github-actions · 2026-01-24T22:17:10Z

⚠️ API/ABI changes detected!

This PR contains changes that modified the public API. To update the reference ABI dumps:

./gradlew updateLegacyAbi
git add **/api/**
git commit -m "Update ABI reference"
git push

After updating, the CI will pass. Make sure the changes are backward compatible.

Copilot

Pull request overview

Introduces a modular hook system for Surf API plugins, including compile-time hook metadata generation and runtime hook discovery/lifecycle management across supported server platforms.

Changes:

Added hook API + lifecycle (AbstractHook, SurfHookApi) and dependency annotations (DependsOn*).
Implemented runtime hook loading/validation via HookService with platform implementations (Paper/Bukkit, Velocity) and a fallback.
Added a KSP processor to generate surf-hooks.json during compilation and wired it into the gradle processor module.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
surf-api-velocity/surf-api-velocity-server/src/main/kotlin/dev/slne/surf/surfapi/velocity/server/hook/VelocityHookService.kt	Velocity implementation of `HookService` for resource/classloader access and plugin checks.
surf-api-gradle-plugin/surf-api-processor/src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider	Registers the new hook KSP processor provider alongside the existing AutoService provider.
surf-api-gradle-plugin/surf-api-processor/src/main/kotlin/dev/slne/surf/surfapi/processor/util/util.kt	Adds shared KSP utilities for deriving binary class names.
surf-api-gradle-plugin/surf-api-processor/src/main/kotlin/dev/slne/surf/surfapi/processor/hook/PluginHookMeta.kt	Defines the serialized hook metadata model used by the processor output.
surf-api-gradle-plugin/surf-api-processor/src/main/kotlin/dev/slne/surf/surfapi/processor/hook/HookSymbolProcessorProvider.kt	Adds KSP provider for hook metadata generation.
surf-api-gradle-plugin/surf-api-processor/src/main/kotlin/dev/slne/surf/surfapi/processor/hook/HookSymbolProcessor.kt	Implements hook annotation scanning and `surf-hooks.json` generation.
surf-api-gradle-plugin/surf-api-processor/src/main/kotlin/dev/slne/surf/surfapi/processor/autoservice/AutoServiceSymbolProcessor.kt	Refactors to use the shared binary-name utility.
surf-api-gradle-plugin/surf-api-processor/build.gradle.kts	Enables serialization support and adds JSON serialization dependency for the processor.
surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/impl/hook/SurfHookApiImpl.kt	Runtime implementation of `SurfHookApi` delegating to `HookService`.
surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/hook/PluginHookMeta.kt	Runtime model for decoding `surf-hooks.json`.
surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/hook/HookServiceFallback.kt	Fallback service when hooks aren’t supported on the current platform.
surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/hook/HookService.kt	Core runtime hook discovery, dependency checks, caching, and ordering.
surf-api-core/surf-api-core-server/src/main/java/dev/slne/surf/surfapi/core/server/impl/reflection/SurfInvocationHandlerJava.java	Updates reflection proxy implementation to use `privateLookupIn` and adjusts method resolution.
surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/hook/requirement/DependsOnPlugin.kt	Adds plugin dependency annotation.
surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/hook/requirement/DependsOnOnePlugin.kt	Adds “one-of” plugin dependency annotation.
surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/hook/requirement/DependsOnClassName.kt	Adds class-name dependency annotation.
surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/hook/requirement/DependsOnClass.kt	Adds class dependency annotation.
surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/hook/SurfHookApi.kt	Defines the public hook API entrypoint and singleton accessor.
surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/hook/HookMeta.kt	Adds hook metadata annotation (priority).
surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/hook/AbstractHook.kt	Adds base hook lifecycle + priority ordering.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/reflection/Reflection.kt	Registers `JavaPluginProxy` and adjusts classloader access usage.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/reflection/JavaPluginProxy.kt	Adds reflection proxy for accessing `JavaPlugin` classloader.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/impl/glow/entity/EntityGlowingData.kt	Fixes `TeamData` companion access.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/hook/PaperHookService.kt	Paper/Bukkit implementation of `HookService`.
surf-api-bukkit/surf-api-bukkit-plugin-test/src/main/kotlin/dev/slne/surf/surfapi/bukkit/test/hook/TestHook.kt	Adds an example hook demonstrating dependency annotations and lifecycle logs.
surf-api-bukkit/surf-api-bukkit-plugin-test/src/main/kotlin/dev/slne/surf/surfapi/bukkit/test/BukkitPluginMain.kt	Updates test plugin to invoke hook lifecycle in async plugin lifecycle methods.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

...rf-api-processor/src/main/kotlin/dev/slne/surf/surfapi/processor/hook/HookSymbolProcessor.kt

...ity-server/src/main/kotlin/dev/slne/surf/surfapi/velocity/server/hook/VelocityHookService.kt

...c/main/java/dev/slne/surf/surfapi/core/server/impl/reflection/SurfInvocationHandlerJava.java

...e/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/hook/HookService.kt

...shared-internal/src/main/kotlin/dev/slne/surf/surfapi/shared/internal/hook/PluginHookMeta.kt

github-actions · 2026-01-24T22:28:32Z

⚠️ API/ABI changes detected!

This PR contains changes that modified the public API. To update the reference ABI dumps:

./gradlew updateLegacyAbi
git add **/api/**
git commit -m "Update ABI reference"
git push

After updating, the CI will pass. Make sure the changes are backward compatible.

Copilot · 2026-01-24T22:30:44Z

@twisti-dev I've opened a new pull request, #190, to work on those changes. Once the pull request is ready, I'll request review from you.

… DependsOnHook annotation

github-actions · 2026-01-25T17:28:18Z

⚠️ API/ABI changes detected!

This PR contains changes that modified the public API. To update the reference ABI dumps:

./gradlew updateLegacyAbi
git add **/api/**
git commit -m "Update ABI reference"
git push

After updating, the CI will pass. Make sure the changes are backward compatible.

github-actions · 2026-01-25T17:43:14Z

⚠️ API/ABI changes detected!

This PR contains changes that modified the public API. To update the reference ABI dumps:

./gradlew updateLegacyAbi
git add **/api/**
git commit -m "Update ABI reference"
git push

After updating, the CI will pass. Make sure the changes are backward compatible.

…ndling

twisti-dev · 2026-01-25T17:49:49Z

@codex review

chatgpt-codex-connector · 2026-01-25T17:49:58Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

github-actions · 2026-01-25T17:52:18Z

⚠️ API/ABI changes detected!

This PR contains changes that modified the public API. To update the reference ABI dumps:

./gradlew updateLegacyAbi
git add **/api/**
git commit -m "Update ABI reference"
git push

After updating, the CI will pass. Make sure the changes are backward compatible.

Copilot

Pull request overview

Copilot reviewed 53 out of 55 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

surf-api-core/surf-api-core-api/api/surf-api-core-api.api

Copilot · 2026-01-25T18:05:07Z

...e/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/hook/HookService.kt

+        }
+
+        validHooks.forEach { (meta, _) -> visit(meta.className) }
+        return sorted.sortedBy { it.priority }


topologicalSort builds a dependency-respecting order via DFS in sorted, but the final sorted.sortedBy { it.priority } reorders hooks and can violate declared DependsOnHook ordering (a dependent hook may run before its dependency). Return the computed topological order as-is, or incorporate priority as a tie-breaker during traversal / Kahn’s algorithm without re-sorting the final list.

Suggested change

return sorted.sortedBy { it.priority }

return sorted

@copilot open a new pull request to apply changes based on this feedback

...rf-api-processor/src/main/kotlin/dev/slne/surf/surfapi/processor/hook/HookSymbolProcessor.kt

surf-api-core/surf-api-core-api/build.gradle.kts

surf-api-core/surf-api-core-server/build.gradle.kts

gradle/wrapper/gradle-wrapper.properties

github-actions · 2026-01-25T19:37:24Z

⚠️ API/ABI changes detected!

This PR contains changes that modified the public API. To update the reference ABI dumps:

./gradlew updateLegacyAbi
git add **/api/**
git commit -m "Update ABI reference"
git push

After updating, the CI will pass. Make sure the changes are backward compatible.

Copilot · 2026-01-25T19:37:30Z

@twisti-dev I've opened a new pull request, #191, to work on those changes. Once the pull request is ready, I'll request review from you.

github-actions · 2026-01-25T19:41:29Z

⚠️ API/ABI changes detected!

This PR contains changes that modified the public API. To update the reference ABI dumps:

./gradlew updateLegacyAbi
git add **/api/**
git commit -m "Update ABI reference"
git push

After updating, the CI will pass. Make sure the changes are backward compatible.

…ng DFS Co-authored-by: twisti-dev <76837088+twisti-dev@users.noreply.github.com>

github-actions · 2026-01-25T19:42:08Z

⚠️ API/ABI changes detected!

This PR contains changes that modified the public API. To update the reference ABI dumps:

./gradlew updateLegacyAbi
git add **/api/**
git commit -m "Update ABI reference"
git push

After updating, the CI will pass. Make sure the changes are backward compatible.

Co-authored-by: twisti-dev <76837088+twisti-dev@users.noreply.github.com>

…rithm with priority tie-breaking (#191)

feat: introduce hook framework with processor, annotations, and integ…

a1112ea

…rations for Bukkit, Velocity, and core APIs

twisti-dev self-assigned this Jan 24, 2026

Copilot AI review requested due to automatic review settings January 24, 2026 22:09

Copilot started reviewing on behalf of twisti-dev January 24, 2026 22:10 View session

chore: update ABI and bump version [skip ci]

f4a0340

chatgpt-codex-connector bot reviewed Jan 24, 2026

View reviewed changes

...rf-api-processor/src/main/kotlin/dev/slne/surf/surfapi/processor/hook/HookSymbolProcessor.kt Show resolved Hide resolved

...ity-server/src/main/kotlin/dev/slne/surf/surfapi/velocity/server/hook/VelocityHookService.kt Show resolved Hide resolved

twisti-dev added 2 commits January 24, 2026 23:14

feat: refactor VelocityHookService to use classloader for resource re…

c5619cf

…trieval

Merge remote-tracking branch 'origin/feat/hook-api' into feat/hook-api

25db719

Copilot AI reviewed Jan 24, 2026

View reviewed changes

twisti-dev added 2 commits January 24, 2026 23:25

Fix hook metadata emission on unresolved deps

f693a76

Fix hook metadata emission when class deps are unresolved (#189)

c29cbc4

Update ABI reference

153a7dc

Copilot AI mentioned this pull request Jan 24, 2026

Extract PluginHookMeta to shared surf-api-common module #190

Closed

twisti-dev added 3 commits January 24, 2026 23:32

feat: improve error handling for hooks metadata loading

cdfca6c

feat: introduce shared hook metadata and configuration classes

b342e50

feat: refactor hook architecture to use shared Hook interface and add…

1c47e83

… DependsOnHook annotation

feat: add conditional hook evaluation with custom conditions support

e12ea89

feat: implement conditional hook support and enhance configuration ha…

41f5bdd

…ndling

twisti-dev requested a review from Copilot January 25, 2026 17:49

Copilot started reviewing on behalf of twisti-dev January 25, 2026 17:50 View session

feat: add shared Hook interface and enhance hook condition handling

e4f9736

Copilot AI reviewed Jan 25, 2026

View reviewed changes

feat: implement topological sort algorithm for directed graphs

ef61b30

Initial plan

0471e83

Copilot AI mentioned this pull request Jan 25, 2026

Fix topological sort violating hook dependencies by using Kahn's algorithm with priority tie-breaking #191

Merged

twisti-dev added 2 commits January 25, 2026 20:38

feat: handle unresolved class dependencies in hook processing

4d18670

feat: remove unused Kotlin compiler options for InternalSurfApi

16cc998

fix: preserve topological order by using priority as tie-breaker duri…

ea677c5

…ng DFS Co-authored-by: twisti-dev <76837088+twisti-dev@users.noreply.github.com>

twisti-dev and others added 5 commits January 25, 2026 20:42

chore: dump abi

85b4f1b

refactor: filter dependencies before sorting by priority

1a1a0d3

Co-authored-by: twisti-dev <76837088+twisti-dev@users.noreply.github.com>

refactor: use Kahn's algorithm with priority queue for topological sort

0d30fd4

Co-authored-by: twisti-dev <76837088+twisti-dev@users.noreply.github.com>

Fix topological sort violating hook dependencies by using Kahn's algo…

2b3abbb

…rithm with priority tie-breaking (#191)

fix: ensure safe null handling for incoming edges in hook processing

db1645a

feat: hook api #188

Are you sure you want to change the base?

feat: hook api #188

Uh oh!

Conversation

twisti-dev commented Jan 24, 2026

Uh oh!

github-actions bot commented Jan 24, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jan 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jan 24, 2026

Uh oh!

Copilot AI commented Jan 24, 2026

Uh oh!

github-actions bot commented Jan 25, 2026

Uh oh!

github-actions bot commented Jan 25, 2026

Uh oh!

twisti-dev commented Jan 25, 2026

Uh oh!

chatgpt-codex-connector bot commented Jan 25, 2026

Uh oh!

github-actions bot commented Jan 25, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Jan 25, 2026

Choose a reason for hiding this comment

Uh oh!

twisti-dev Jan 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jan 25, 2026

Uh oh!

Copilot AI commented Jan 25, 2026

Uh oh!

github-actions bot commented Jan 25, 2026

Uh oh!

github-actions bot commented Jan 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants