How the Source Fetcher Registry Handles Git and Local File Protocols in TencentDB-Agent-Memory

The SourceFetcherRegistry class in src/source-fetcher/registry.ts automatically classifies source URLs by protocol scheme and routes them to registered fetcher implementations, currently supporting Git repositories while preparing for local file system support.

The Source Fetcher Registry serves as the central routing layer in the TencentDB-Agent-Memory project, abstracting protocol complexity from the knowledge module. By analyzing URL patterns in detectType() and maintaining an internal registry of fetcher implementations, the system decouples protocol detection from retrieval logic, allowing module.ts to fetch code without handling protocol-specific details.

Protocol Detection in the Registry

The registry's private detectType() method implements URL scheme analysis to classify incoming source strings into three categories: git, local, and ftp.

Git URL Patterns

URLs beginning with version control prefixes are mapped to the git type:

• git@ (SSH Git protocol)
• ssh:// (SSH URL scheme)
• https:// or http:// (HTTP-based Git)

The detection logic uses simple string prefix matching:

// src/source-fetcher/registry.ts
private detectType(url: string): SourceType {
  if (url.startsWith("git@") || url.startsWith("ssh://") ||
      url.startsWith("https://") || url.startsWith("http://")) {
    return "git";
  }
  if (url.startsWith("file://") || url.startsWith("/") || url.startsWith("./")) {
    return "local";
  }
  if (url.startsWith("ftp://")) return "ftp";
  return "git";
}

Local File Path Recognition

The registry recognizes local filesystem paths through three distinct patterns:

• file:// (Explicit file protocol)
• / (Absolute Unix paths)
• ./ (Relative paths)

Fallback Strategy

Unrecognized URL patterns default to the git type, ensuring backwards compatibility while maintaining strict type safety through the SourceType union type defined in src/source-fetcher/types.ts.

Git Protocol Implementation

The GitSourceFetcher class in src/source-fetcher/git-fetcher.ts provides the concrete implementation for Git URLs. This fetcher leverages the simple-git library to perform repository operations.

Shallow Cloning and Syncing

The GitSourceFetcher implements two primary operations:

1. fetch() – Performs shallow clones to minimize bandwidth and storage
2. sync() – Handles incremental updates to existing repositories

Security Validation

Before executing Git operations, the fetcher validates that the target URL is a public HTTPS repository. The implementation includes SSRF (Server-Side Request Forgery) protection by optionally blocking private and loopback addresses, ensuring the agent cannot be tricked into accessing internal network resources.

// Usage pattern from src/module.ts
const registry = new SourceFetcherRegistry();
const fetcher = registry.resolve("https://github.com/TencentCloud/TencentDB-Agent-Memory.git");
await fetcher.fetch(repoUrl, branch, destinationPath);

Local File Protocol Support

While the registry can detect local file protocols, the concrete implementation remains a planned extension. The current codebase in src/source-fetcher/registry.ts registers only the GitSourceFetcher in its constructor:

// src/source-fetcher/registry.ts
constructor() {
  this.register(new GitSourceFetcher());
  // Future: this.register(new LocalSourceFetcher());
  // Future: this.register(new FtpSourceFetcher());
}

Future LocalSourceFetcher Architecture

When implemented, a LocalSourceFetcher class will follow the same ISourceFetcher interface defined in src/source-fetcher/types.ts. It will handle file:// URLs and filesystem paths by copying or reading local source files directly, bypassing network operations entirely.

The registry's design ensures that once LocalSourceFetcher is registered via registry.register(new LocalSourceFetcher()), the existing detectType() logic will automatically route local paths to this implementation without modifying consumer code in module.ts.

Fetcher Resolution Workflow

The resolve() method orchestrates the complete routing pipeline:

// src/source-fetcher/registry.ts
resolve(sourceUrl: string): ISourceFetcher {
  const type = this.detectType(sourceUrl);
  const fetcher = this.fetchers.get(type);
  if (!fetcher) {
    throw new Error(`unsupported source type: ${type} (${sourceUrl})`);
  }
  return fetcher;
}

This method executes three distinct steps:

1. Classification – Calls detectType() to determine the SourceType
2. Lookup – Retrieves the matching fetcher from the internal Map<SourceType, ISourceFetcher>
3. Validation – Throws an explicit error if no fetcher exists for the detected type

The error handling prevents runtime failures when encountering unimplemented protocols (such as ftp:// or local files in the current release).

Summary

• The Source Fetcher Registry in src/source-fetcher/registry.ts uses prefix-based pattern matching in detectType() to classify URLs as git, local, or ftp protocols.
• Git URLs (including SSH and HTTP variants) route to GitSourceFetcher, which uses simple-git for shallow clones and includes SSRF protection.
• Local file paths (starting with file://, /, or ./) are recognized but currently throw errors until LocalSourceFetcher is implemented.
• The resolve() method provides a unified interface that returns protocol-specific fetchers, allowing module.ts to remain agnostic to source retrieval mechanisms.
• New fetcher implementations can be added via registry.register() without modifying existing detection logic.

Frequently Asked Questions

How does the Source Fetcher Registry distinguish between Git and local file sources?

The registry examines URL prefixes in the private detectType() method. URLs starting with git@, ssh://, https://, or http:// map to the git type, while those beginning with file://, /, or ./ map to local. Any unrecognized pattern falls back to git as the default type.

What happens when I try to fetch a local file URL in the current version?

The registry will detect the local type via detectType(), but the resolve() method will throw an error stating unsupported source type: local because only GitSourceFetcher is registered in the constructor. Support for local files requires implementing and registering a LocalSourceFetcher class.

How does the GitSourceFetcher protect against SSRF attacks?

The GitSourceFetcher in src/source-fetcher/git-fetcher.ts validates that target URLs point to public HTTPS repositories before cloning. It optionally blocks private IP ranges and loopback addresses, preventing the agent from accessing internal network resources through malicious repository URLs.

Can I add support for additional protocols like FTP?

Yes. Implement the ISourceFetcher interface from src/source-fetcher/types.ts, update detectType() to recognize your protocol prefix (such as ftp://), then register the instance using registry.register(new FtpSourceFetcher()). The existing resolution logic will automatically route matching URLs to your implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}