Activate or create a connection via URL parameters

[kmcginnes]

Problem Statement

Applications that use graph databases have no way to launch Graph Explorer pre-connected to their database. Users must manually open Graph Explorer, create a connection, and configure it — friction that discourages cross-app integration.

Solution

Graph Explorer accepts URL search parameters that specify a database connection. On page load, it either activates a matching existing Connection or prompts the user to create a new one, then lands on the requested page ready to explore.

Example link from an external app:

https://my-ge-host/?graphDbUrl=https%3A%2F%2Fmy-cluster.us-east-1.neptune.amazonaws.com%3A8182&queryEngine=gremlin&awsRegion=us-east-1&serviceType=neptune-db&name=My%20Database#/graph-explorer

Note: The graphDbUrl value must be URL-encoded (e.g., https://host:8182 becomes https%3A%2F%2Fhost%3A8182). Most languages provide this via encodeURIComponent() (JavaScript), urllib.parse.quote() (Python), URLEncoder.encode() (Java), etc.

User Stories

1. As an external app developer, I want to link users to Graph Explorer with a database connection pre-activated, so that users can explore their graph data without manual configuration.
2. As an external app developer, I want to specify the database URL, query language, AWS region, service type, and display name in the link, so that the connection is configured correctly for my database.
3. As a Graph Explorer user, I want to be prompted before a new connection is created from URL parameters, so that arbitrary links cannot silently modify my saved connections.
4. As a Graph Explorer user, I want to edit the connection name in the creation prompt, so that I can personalize how the connection appears in my list.
5. As a Graph Explorer user, I want my existing graph Session to be preserved when a URL targets the connection I am already connected to, so that my exploration work is not lost when nothing actually changes.
6. As a Graph Explorer user, I want the URL parameters stripped after processing, so that refreshing the page or switching connections behaves normally.
7. As an external app developer, I want to control which page the user lands on by setting the hash path (e.g., #/graph-explorer, #/data-explorer), so that I can tailor the landing experience.
8. As a Graph Explorer user, I want only graphDbUrl to be required in the URL, so that simple integrations need minimal configuration (query language defaults to Gremlin, IAM auth assumed off when region/serviceType are absent).
9. As a Graph Explorer user, I want duplicate connections to not be created when I click the same external link multiple times, so that my connection list stays clean.
10. As a Graph Explorer user, I want the URL parameters processed after default connections load, so that default connections are still available alongside the URL-specified connection.
11. As an external app developer, I want the matching logic to find my connection even if the user has renamed it in Graph Explorer, so that name changes don't break integration links.
12. As a Graph Explorer user with multiple connections to the same database, I want the name parameter to disambiguate which connection activates, so that the correct one is chosen.
13. As a Graph Explorer user, I want to cancel the connection creation prompt and remain on my current page with params stripped, so that I'm not forced into creating a connection.

Implementation Decisions

• URL parameter location: Search params outside the hash (window.location.search), not inside it. This makes them accessible without depending on the router and allows a top-level component to intercept them early in the boot sequence.
• Accepted parameters: graphDbUrl (required, must be URL-encoded), queryEngine (optional, default "gremlin"), awsRegion (optional), serviceType (optional), name (optional). If awsRegion and serviceType are absent, IAM auth is assumed off.
• Processing location: Extend AppStatusLoader to process URL params after default connections have been fetched/created. Order: hydrate IndexedDB → fetch default connections → process URL params → render route.
• Matching logic: Filter connections by graphDbUrl (case-insensitive) + queryEngine. If exactly one match, use it. If multiple matches, prefer the already-active connection, then tiebreak by name param, then fall back to first found. If zero matches, prompt for creation.
• Activation behavior: Switching to a different connection resets the Session, identical to a manual connection switch. The previously explored graph state cannot be interacted with once the active connection changes, so it must be cleared. The Session is only preserved when the URL targets the connection that is already active — in that case nothing changes and no reset occurs. (This corrects an earlier version of this issue that proposed activating without a reset.)
• Creation requires user consent: When no match is found, display a modal showing the connection details (editable name, graphDbUrl, queryEngine, region, serviceType) with Create/Cancel buttons. On cancel, params are stripped and the user remains on their current page.
• Connection naming for auto-creation: Use the name URL parameter if provided. Otherwise, derive a display name from the graphDbUrl (e.g., extract the cluster identifier from the hostname). The name is editable in the confirmation modal.
• URL parameter stripping: After processing (whether match-activated or user-confirmed/cancelled creation), use window.history.replaceState to remove search params from the URL. This makes the action a one-shot intent, not persistent state.
• Route handling: The hash portion of the URL determines which page the user lands on. If no hash path is specified, the existing catch-all redirect sends users to /graph-explorer.
• Scope: New tab/window navigation only. No iframe/postMessage support.
• Subsequent navigations: If the user clicks another external link with different params, the browser performs a full page reload (since window.location.search changes), and the boot sequence processes the new params naturally.

Modules

1. URL Connection Params parser — Pure function that reads window.location.search, validates against a schema, and returns a typed params object or null. Handles URL decoding, required vs optional fields, and defaults.
2. Connection matcher — Pure function that takes parsed URL params, a list of existing connections, and the active connection ID, and returns the matched connection ID or null. Encapsulates the full priority logic (filter by dbUrl+queryEngine → prefer active → tiebreak by name → first found).
3. AppStatusLoader extension — Orchestrates the flow: after default connections load, calls the parser; if params exist, calls the matcher; if it matches the already-active connection, does nothing; if it matches a different connection, prompts to switch (resetting the Session on confirm); if no match, renders the create-connection form; after resolution, strips params.
4. Confirmation modal — UI component showing connection details with an editable name field and Create/Cancel buttons.

Testing Decisions

Good tests for this feature verify external behavior (given these URL params and this connection state, what connection is activated / what modal is shown?) rather than implementation details (which atoms were set, which internal functions were called).

Modules to test

1. URL Connection Params parser — Test valid param combinations, missing required params, defaults applied, URL decoding, and invalid values rejected. Prior art: defaultConnection.test.ts (schema validation pattern with DefaultConnectionDataSchema).
2. Connection matcher — Test single match, multiple match disambiguation (active preferred, then name tiebreak, then first), zero matches returning null, case-insensitive URL comparison. Prior art: exportedGraph.test.ts (isMatchingConnection tests).
3. AppStatusLoader extension — Integration test that verifies the full sequence: params present → connection activated → params stripped. Also: params present with no match → modal rendered. Prior art: defaultConnection.test.ts (loading/creating connections at boot).
4. Confirmation modal — Render with props, verify displayed info, test Create callback fires with correct data, test Cancel strips params without creating. Prior art: component tests using Testing Library patterns found in the codebase.

Out of Scope

• Iframe embedding or postMessage-based communication with parent applications
• Proxy server configuration parameters (removed per PR Unify Docker image by removing SageMaker variant #1773)
• Sharing or encoding graph Session state (vertices/edges) in URL parameters
• Authentication token passing via URL (security risk)
• Bidirectional communication (GE notifying the external app of user actions)
• Multi-connection activation (only one connection at a time)
• fetchTimeoutMs or nodeExpansionLimit as URL parameters (too implementation-specific for external callers)

Further Notes

• This feature depends on PR Unify Docker image by removing SageMaker variant #1773 landing first, which simplifies the Connection model to use graphDbUrl as the single required field.
• The isMatchingConnection function in exportedGraph.ts is prior art for matching logic, but the new matcher module should be independent since post-Unify Docker image by removing SageMaker variant #1773 the connection model changes.
• URL-driven activation reuses today's manual connection-switching behavior, including the Session reset. There is no special "activate without reset" path: a loaded graph cannot be interacted with once the active connection changes, so switching connections must clear it. Only a URL that targets the already-active connection skips the reset, because nothing changes.
• External apps must URL-encode parameter values. The graphDbUrl in particular contains characters (:, /) that are invalid in query string values without encoding.

[andy-k-improving]

1. What defines a "connection" for matching purposes? Is it the tuple of (graphDbUrl, queryEngine), or does it also include name/ID? The matching logic in the spec filters by graphDbUrl + queryEngine, but the disambiguation step uses name — so what is the actual unique identifier of a connection internally?

2. Story 11 implies matching survives a rename. Does this mean Graph Explorer tracks a stable internal ID (separate from the display name) that the URL matching resolves against? If so, what is that ID — is it auto-generated, or derived from the connection parameters?

3. Story 12 uses name as a tiebreaker when multiple connections share the same graphDbUrl + queryEngine. Does this mean name must be unique across connections to the same database? If a user renames connection A to match connection B's name, does that create an ambiguity the matcher can't resolve?

[kmcginnes]

Connections are matched by value:

DB URL + query language + IAM parameters

There's an internal UUID per connection, but it's per-user and not exposed in URLs. We could include it, but then a missing connection ID would trigger connection creation even when a matching connection already exists (e.g. added as a default, imported from JSON).

Since matching is value-based, renames don't break anything — name is only used as a disambiguation hint when multiple connections share the same value tuple. If multiple still match, we pick the first (or we could prompt the user to choose).

[andy-k-improving]

Connections are matched by value:

DB URL + query language + IAM parameters

There's an internal UUID per connection, but it's per-user and not exposed in URLs. We could include it, but then a missing connection ID would trigger connection creation even when a matching connection already exists (e.g. added as a default, imported from JSON).

Since matching is value-based, renames don't break anything — name is only used as a disambiguation hint when multiple connections share the same value tuple. If multiple still match, we pick the first (or we could prompt the user to choose).

So connection name will never be considered when matching connection logic, right?

[kmcginnes]

The pseudocode for this would be:

const matchingConnections = connections
  .filter(matchesByValue(targetConnection));
if (matchingConnections.length === 1)
  return matchingConnections[0];
else if (matchingConnections.length > 1)
  return matchingConnections
    .filter(matchesByName(targetConnectionName)[0] ?? matchingConnections[0];
else
  return null;

[kmcginnes]

@andy-k-improving I marked this blocked by #1772 because if we don't do that change first, then the connection parameters need to include the proxy server URL as well. This is a bit counterintuitive because the proxy URL is likely the same as the request base URL with a minor tweak.