Repository navigation
ADFA-7139: Plugin API for the SQLite debugger endpoints #2261
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
davidschachterADFA
wants to merge
8
commits into
sqlite-debugger/ADFA-7137
Choose a base branch
from
sqlite-debugger/ADFA-7139
base: sqlite-debugger/ADFA-7137
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
c72508a
ADFA-7139 Add DebuggerEndpointService and the debugger.endpoints perm…
davidschachterADFA a84d59b
ADFA-7139 Implement DebuggerEndpointService in plugin-manager
davidschachterADFA 030c678
ADFA-7139 Serve the stored debugger endpoints to plugins
davidschachterADFA 4181e7c
ADFA-7139 Docs: describe DebuggerEndpointService in the sqlite-debugg…
davidschachterADFA 6a99814
ADFA-7139 Leave uninstalled apps out of the endpoints and rethrow int…
davidschachterADFA cbe541a
ADFA-7139 Docs: DebuggerEndpointService ships in 26.47, not 26.43
davidschachterADFA aa86aa1
ADFA-7139: Merge ADFA-7137 (with #2244's sqlite-js 1.4.3) up the stack
davidschachterADFA 2007193
ADFA-7139: Merge ADFA-7137 (README corrections) up the stack
davidschachterADFA File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
101 changes: 101 additions & 0 deletions
101
plugin-api/src/main/java/com/itsaky/androidide/plugins/services/DebuggerEndpoint.java
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,101 @@ | ||
| package com.itsaky.androidide.plugins.services; | ||
|
|
||
| import androidx.annotation.NonNull; | ||
| import java.util.Objects; | ||
|
|
||
| /** | ||
| * Where one app's SQLite debugger server is listening, as the app last reported it to the IDE. Immutable. | ||
| * | ||
| * <p> | ||
| * The port and the token are chosen by the app on every start, so a value read here goes stale when the app dies or is relaunched; a client that is refused (or answered 401/403) asks {@link DebuggerEndpointService#getEndpoints} again instead of retrying the same values. The token is a credential for the debugger server: do not log it or persist it. {@link #toString} leaves it out. | ||
| * | ||
| * <p> | ||
| * An endpoint whose app has been uninstalled is not returned, but one whose process has died is: nothing removes it until the app reports again. {@link #getUpdatedAtMillis} is when the app last reported, not a sign that it is still running. | ||
| */ | ||
| public final class DebuggerEndpoint { | ||
|
|
||
| private final String applicationId; | ||
| private final int port; | ||
| private final String token; | ||
| private final long updatedAtMillis; | ||
|
|
||
| /** | ||
| * Creates an endpoint. | ||
| * | ||
| * @param applicationId | ||
| * the app's package name (must not be null) | ||
| * @param port | ||
| * the TCP port the debugger server listens on, on the loopback interface | ||
| * @param token | ||
| * the bearer token the server requires (must not be null) | ||
| * @param updatedAtMillis | ||
| * when the app reported these values, in milliseconds since the Unix epoch | ||
| */ | ||
| public DebuggerEndpoint(@NonNull String applicationId, int port, @NonNull String token, long updatedAtMillis) { | ||
| this.applicationId = Objects.requireNonNull(applicationId, "applicationId"); | ||
| this.port = port; | ||
| this.token = Objects.requireNonNull(token, "token"); | ||
| this.updatedAtMillis = updatedAtMillis; | ||
| } | ||
|
|
||
| @Override | ||
| public boolean equals(Object other) { | ||
| if (this == other) { | ||
| return true; | ||
| } | ||
| if (!(other instanceof DebuggerEndpoint)) { | ||
| return false; | ||
| } | ||
| final DebuggerEndpoint that = (DebuggerEndpoint) other; | ||
| return port == that.port && updatedAtMillis == that.updatedAtMillis && applicationId.equals(that.applicationId) && token.equals(that.token); | ||
| } | ||
|
|
||
| /** | ||
| * Gets the app's package name, which identifies the app within the project. | ||
| * | ||
| * @return the application ID (never null) | ||
| */ | ||
| @NonNull | ||
| public String getApplicationId() { | ||
| return applicationId; | ||
| } | ||
|
|
||
| /** | ||
| * Gets the port the debugger server listens on, on {@code 127.0.0.1}. | ||
| * | ||
| * @return the port | ||
| */ | ||
| public int getPort() { | ||
| return port; | ||
| } | ||
|
|
||
| /** | ||
| * Gets the bearer token the server requires on every request. | ||
| * | ||
| * @return the token (never null) | ||
| */ | ||
| @NonNull | ||
| public String getToken() { | ||
| return token; | ||
| } | ||
|
|
||
| /** | ||
| * Gets when the app reported {@link #getPort} and {@link #getToken}. | ||
| * | ||
| * @return milliseconds since the Unix epoch | ||
| */ | ||
| public long getUpdatedAtMillis() { | ||
| return updatedAtMillis; | ||
| } | ||
|
|
||
| @Override | ||
| public int hashCode() { | ||
| return Objects.hash(applicationId, port, token, updatedAtMillis); | ||
| } | ||
|
|
||
| @NonNull | ||
| @Override | ||
| public String toString() { | ||
| return "DebuggerEndpoint{applicationId=" + applicationId + ", port=" + port + ", updatedAtMillis=" + updatedAtMillis + "}"; | ||
| } | ||
| } |
36 changes: 36 additions & 0 deletions
36
plugin-api/src/main/java/com/itsaky/androidide/plugins/services/DebuggerEndpointService.java
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| package com.itsaky.androidide.plugins.services; | ||
|
|
||
| import androidx.annotation.NonNull; | ||
| import java.util.List; | ||
|
|
||
| /** | ||
| * Tells a plugin where the SQLite debugger servers of the open project's apps are listening, so a plugin such as an MCP client can connect without the user typing a port or token. | ||
| * | ||
| * <p> | ||
| * The host registers this service for every plugin; a call needs the {@link com.itsaky.androidide.plugins.PluginPermission#DEBUGGER_ENDPOINTS} permission and throws {@link SecurityException} without it, like the other permission-gated services. | ||
| * | ||
| * <p> | ||
| * Calls are synchronous, as in {@link IdeLogService} and {@link IdeProjectService}, rather than returning a {@link java.util.concurrent.CompletableFuture} as the services that start long work do: the answer is a small read of the IDE's own database, not an operation with a lifecycle. That read is disk I/O, so call from a background thread: on the main thread the call throws {@link IllegalStateException}. | ||
| */ | ||
| public interface DebuggerEndpointService { | ||
|
|
||
| /** | ||
| * Contract revision, bumped whenever a member is added here. It marks the revision and does not negotiate one; see {@link ToolSourceRegistry#CONTRACT_VERSION}. | ||
| */ | ||
| int CONTRACT_VERSION = 1; | ||
|
|
||
| /** | ||
| * Gets the debugger endpoints of the open project, one per app that has reported. Read fresh on every call, so call it again after a connection fails: a relaunched app has a new port and token. | ||
| * | ||
| * <p> | ||
| * An app the IDE installed or launched but that has not yet reported is not listed, and neither is an app that has since been uninstalled. An endpoint can still be stale: when the app's process has died, its last reported port and token stay here until the app reports again, so treat {@link DebuggerEndpoint#getUpdatedAtMillis} (when it last reported) as a hint, and when a connection is refused, call this again and reconnect. | ||
| * | ||
| * @return the endpoints (never null; empty when no project is open or no app has reported) | ||
| * @throws SecurityException | ||
| * if the plugin lacks the {@code debugger.endpoints} permission | ||
| * @throws IllegalStateException | ||
| * if called on the main thread, or if the IDE's database could not be read. A failed read is not the same as no apps: keep what you had and try again later | ||
| */ | ||
| @NonNull | ||
| List<DebuggerEndpoint> getEndpoints(); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
MINOR:
reportedEndpointsreturns every stored row with a token and port, with no age or liveness bound.The row survives the app being killed or uninstalled (nothing in
DebuggerEndpointDaoclears token/port exceptclearEndpointIfProjectDifferson a project move). A plugin callinggetEndpoints()then gets a dead endpoint, and the bearer token goes to whatever listens on that port next. Not reachable as a bug today because the API docs tell callers to re-ask after a refused connection or 401/403 and the token only goes to 127.0.0.1, and the only consumer (addons#166) is in a separate PR I did not verify for this. A client that ignoresupdatedAtMillisis the one at risk.Say in the KDoc here (or the plugin-api docs) that rows are not pruned, so clients treat
updatedAtMillisas a hint, or filter out rows older than some bound.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed in 6a99814: endpoints of apps that are no longer installed are left out (injected check; PackageManager in the app; every package is visible because Code on the Go targets SDK 28). The Javadoc now says an endpoint can still be stale after the process dies, that
updatedAtMillisis when it last reported, and that clients reconnect after a refused connection.