feat: Support file:// URLs for OData metadata in CREATE ODATA CLIENT

[dionesiusap]

Problem

When creating consumed OData services with CREATE ODATA CLIENT, the MetadataUrl parameter currently only supports HTTP/HTTPS URLs. This creates friction in several scenarios:

• Offline development — developers working without network access cannot create OData clients
• Testing and CI/CD — test environments often use local metadata snapshots to ensure reproducibility
• Version-pinned metadata — teams want to lock to a specific metadata version rather than fetching from a live service
• Pre-production services — metadata for services under development may only exist as files, not deployed endpoints

Proposed Solution

Allow MetadataUrl to accept file:// URLs pointing to local XML metadata files:

```mdl
-- Absolute path
CREATE ODATA CLIENT MyModule.ExternalAPI (
MetadataUrl: 'file:///Users/username/projects/metadata/service.xml'
);

-- Relative path (relative to project .mpr directory)
CREATE ODATA CLIENT MyModule.LocalService (
MetadataUrl: 'file://./metadata/local-service.xml'
);
```

Key Behavior

1. Protocol detection — If MetadataUrl starts with file://, read from local filesystem instead of HTTP
2. Path resolution:
   • file:///absolute/path → absolute path
   • file://./relative/path → relative to .mpr file directory
3. Hash calculation — SHA256 hash computed identically to HTTP-fetched metadata (for change detection)
4. Backwards compatible — existing HTTP/HTTPS URLs work unchanged

Benefits

• Offline development — no network required to set up OData clients
• Reproducibility — metadata snapshots ensure consistent test/CI behavior
• Team collaboration — commit metadata files alongside code in version control
• Pre-production integration — test against upcoming API changes before deployment
• Firewall-friendly — works in locked-down corporate environments

Implementation Details

See full proposal: `docs/11-proposals/PROPOSAL_odata_local_metadata.md`

Estimated effort: 2-3 hours

[github-actions]

Issue Triage

Summary:
The issue requests adding support for file:// URLs in the MetadataUrl parameter of CREATE ODATA CLIENT so developers can point to local OData metadata files for offline work, testing, and CI/CD scenarios.

Checklist for feature request

Required info	Present?	Details
Use case – why the feature is needed	✅	Lists offline development, firewall restrictions, reproducibility, version‑pinned metadata, and pre‑production services.
Proposed syntax or behavior	✅	Shows absolute and relative file:// examples, protocol detection, path resolution, hash calculation, and backward compatibility.
Mendix version relevance (if version‑specific)	❌	No mention of which Mendix versions this applies to or any version‑specific considerations.

Next steps
Could you please clarify whether this feature is intended for all Mendix versions or if there are any version‑specific constraints (e.g., only works with Mendix 10.x and above)? Adding that information will help reviewers assess the request more easily. Thank you!

---

Automated triage via OpenRouter — workflow source

[ako]

Reviewed. Sound proposal, narrow scope — worth doing. A few design points worth resolving before implementation:

Scope check. Only one fetch site exists: fetchODataMetadata() at mdl/executor/cmd_odata.go:1409. AsyncAPI contracts are stored as Document on the service (no URL fetch), so OData is the only consumer of this pattern today. Good, contained change.

Design points

1. file://./relative/path is non-standard. Per RFC 8089 a file:// URI has either an empty host (file:///abs/path) or a real host component. file://./path parses as host="." — unusual and will trip up net/url. Two cleaner options:

   • Accept a bare path alongside file:///abs/path (./metadata/x.xml, metadata/x.xml).
   • Support only file:///… absolute and require pre-resolution.

   I'd lean toward the first — MDL is a pragmatic DSL and bare relative paths are unambiguous. Suggest dropping file://./… from the spec.

2. "Relative to project directory" needs a precise definition. The executor doesn't always have a loaded .mpr in scope (e.g., mxcli check with no -p). What's the base directory when no project is loaded — cwd? The MDL script's directory? Please state explicitly and cover with a test.

3. Reuse the existing helper. cmd/mxcli/lsp_helpers.go:33 already has uriToPath() using net/url. Prefer it over ad-hoc strings.HasPrefix("file://") parsing — handles URL-encoded paths and (eventually) Windows drives correctly.

4. Referenced proposal isn't in the repo. The issue cites docs/11-proposals/PROPOSAL_odata_local_metadata.md; no such file exists on main. Either it's in an unshipped branch or aspirational — could you either push it or drop the reference?

5. Hash-on-file semantics. Worth documenting that editing the local file invalidates the cached metadata just like a live service change would. Desired behavior, but users should know.

Security: MDL scripts are already trusted input (they mutate the project on the user's behalf), so reading a user-chosen local file isn't new exposure.

Suggested minimal spec

MetadataUrl accepts:
  https://…            HTTP(S) fetch (existing)
  http://…             HTTP(S) fetch (existing)
  file:///abs/path     Local absolute path
  ./path, path/x.xml   Local path relative to the .mpr project dir
                       (or cwd if no project loaded)

Happy to pair on the implementation once the relative-path resolution rule is nailed down.

[dionesiusap]

Thanks for the detailed review. All points are well taken. Here's how I'll address them:

1. Relative path syntax — Agreed, will use the minimal spec you suggested:

MetadataUrl accepts:
  https://…            HTTP(S) fetch (existing)
  http://…             HTTP(S) fetch (existing)
  file:///abs/path     Local absolute path
  ./path, path/x.xml   Local path relative to the .mpr project dir
                       (or cwd if no project loaded)

2. Base directory resolution — Proposed rule:

• With project loaded (-p flag or REPL): relative to the .mpr file's directory
• No project loaded (mxcli check without -p): relative to cwd
• Will add test coverage for both scenarios

3. Using uriToPath() — Will reuse the existing helper from lsp_helpers.go instead of ad-hoc string parsing.

4. Proposal document — Will inline the full spec in the PR description instead of a separate proposal file.

5. Hash invalidation — Will document that editing the local XML file invalidates cached metadata (same behavior as remote service changes).

Let me know if the base directory rule needs adjustment before I start implementation. Happy to pair if you'd like to work through it together.

[dionesiusap]

Implementation Question: Path Utility Reuse

During implementation, I've identified that we need a uriToPath() helper to handle file:// URL parsing. This function already exists in cmd/mxcli/lsp_helpers.go (5 lines, using net/url.Parse).

Two viable approaches:

Option 1: Reimplement in executor package

Copy the function into mdl/executor/ (likely in helpers.go or cmd_odata.go).

Pros:

• Self-contained, no new packages
• Fast to implement and review
• Zero dependency changes

Cons:

• Code duplication (two copies of the same 5-line function)
• Must maintain both if bugs are found

Option 2: Extract to shared utility package

Create internal/pathutil package, move the function there, update both call sites.

Pros:

• Single source of truth
• Reusable for future path utilities
• Follows Go's internal/ pattern for shared code

Cons:

• Broader PR scope (refactors existing LSP code)
• More files to review

Note: Importing directly from cmd/mxcli is technically possible but architecturally unclean (executor shouldn't depend on CLI layer, and the function is unexported anyway).

I'm leaning toward Option 2 for better long-term maintainability, but wanted to check if there's a preference or existing pattern I should follow. Thoughts?