If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/lionsoul2014/ip2region shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 3 active contributors
• Apache-2.0 licensed
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 94% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live lionsoul2014/ip2region repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/lionsoul2014/ip2region.

What it runs against: a local clone of lionsoul2014/ip2region — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in lionsoul2014/ip2region | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of lionsoul2014/ip2region. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/lionsoul2014/ip2region.git
#   cd ip2region
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of lionsoul2014/ip2region and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "lionsoul2014/ip2region(\\.git)?\\b" \\
  && ok "origin remote is lionsoul2014/ip2region" \\
  || miss "origin remote is not lionsoul2014/ip2region (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/lionsoul2014/ip2region"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ip2region is an offline IP-to-geolocation library that maps IPv4 and IPv6 addresses to country/province/city/ISP with 10-microsecond query latency. It provides xdb (extensible database), a compressed binary format supporting hundreds of millions of IP ranges, plus client libraries for 12+ languages to enable fast, zero-dependency IP localization without external APIs. Monorepo with language-specific bindings: binding/{golang,java,php,python,c,cpp,rust,javascript,csharp,erlang,lua,cangjie} each contain searcher implementations, Makefiles, and tests. Core logic is language-agnostic xdb binary format parsing. Data pipeline: raw data in data/{ipv4,ipv6}source.txt → (generation step, not visible in repo) → data/ip2region{v4,v6}.xdb consumed by all searchers. Root has LICENSE, Makefile for multi-language builds.

Backend engineers and infrastructure teams deploying IP geolocation features (fraud detection, analytics, CDN routing, regional content blocking) who need sub-100-microsecond lookup without network calls. Also IP data custodians managing large custom IP-to-metadata mappings via the xdb framework.

Production-ready. The project has multi-language bindings (Go, Java, C, PHP, Python, Rust, JavaScript, C#, C++, Erlang, Lua, Cangjie) with complete test suites in binding/*/tests, pre-built xdb files in data/, and active maintenance across 12 language ecosystems. Evidence: 140KB+ Java code, 128KB+ Go code, organized binding structure, and dual IPv4/IPv6 support indicate substantial real-world usage.

Low risk for core functionality, moderate risk for custom extensions. The xdb format is stable (version-compatible searchers exist), but the project is primarily maintained by a single author (@lionsoul2014), creating single-point-of-failure risk. No external runtime dependencies (see binding/golang/go.mod only needs mitchellh/go-homedir), but custom region data corruption during xdb generation could silently break production queries—test your xdb generation pipeline thoroughly.

Unable to determine from static file list alone—no visible git log, GitHub issues, or PR data provided. However, the presence of binding/cangjie/ (a newer language with .cj extension) and comprehensive test coverage in binding/cangjie/src/tests/ suggests recent additions. The Makefile and consistent binding structure indicate ongoing maintenance across all supported languages.

git clone https://github.com/lionsoul2014/ip2region.git
cd ip2region
# Pick your language. For Go:
cd binding/golang
go build
# For Java:
cd binding/java
mvn clean package
# Data files already committed:
ls -la ../../data/ip2region_v*.xdb

Daily commands: No monolithic 'dev server.' Each binding is independent: cd binding/{language} && make or language-specific build (mvn for Java, cargo for Rust, npm for JavaScript). Query workflow: new Searcher(xdb_path) → searcher.searchByIp(ip_string) → {country, province, city, isp, iso_code}. See binding/*/README.md for exact syntax per language.

• binding/golang/xdb_searcher.go: Reference implementation of xdb binary parsing; defines vIndex caching strategy and B-tree block traversal—essential to understand before implementing other language bindings
• binding/java/src/main/java/net/ip2region/XdbSearcher.java: Java reference showing complete searcher logic with error handling; largest production-grade implementation (140KB+ Java code suggests this is heavily used)
• binding/c/xdb_searcher.c: Low-level C implementation of xdb parsing; reveals memory-efficient block reading patterns and union-based region data unpacking required for performance
• data/ip2region_v4.xdb: Compiled binary xdb database for IPv4; actual artifact consumed by all searchers—understand its structure by reading searcher implementations
• binding/golang/xdb_util.go: Contains IP-to-integer conversion, CRC32 validation, byte unpacking—shared logic critical for correctness across all bindings
• binding/cangjie/src/xdb/searcher.cj: Newest binding (Cangjie language); shows how to port xdb to an emerging language—template for adding new language support

To fix a bug or add a feature: (1) xdb format/generation logic: not visible in repo—likely separate data pipeline. (2) Add a new language binding: copy binding/c/ or binding/golang/ structure; implement xdb_searcher (reads blocks, binary parsing), xdb_header (version check), xdb_util (IP→int, crc32). (3) Improve existing searcher: edit binding/{lang}/src/ (e.g., binding/java/src/main/java/net/ip2region/). (4) Add tests: binding/{lang}/src/tests/ using language native test framework. (5) Update data: regenerate data/ip2region_v*.xdb from raw source (tool not in repo, likely separate).

xdb binary format not documented in repo: no spec file or detailed format definition visible—must reverse-engineer from searcher source code. Data generation pipeline missing: data/ipv4_source.txt and data/ipv6_source.txt are not in file list, nor is the code that generates .xdb files—external tool or separate repo. CRC32 validation: xdb_util implementations validate trailing CRC32; if corrupted, all searchers fail silently or throw opaque errors—always verify downloaded xdb files. Vector index memory: vIndex caching uses fixed 512KiB; changing this requires rebuilding xdb (not possible in repo). Language version constraints: binding/golang/go.mod specifies go 1.18; some older bindings (e.g., PHP5 vs PHP7) may have unspecified minimum versions—check binding/{lang}/README.md. No Docker base image for data generation: Dockerfile (2126 bytes) likely exists but its purpose (build xdb, serve queries, test suite?) is not evident from file list alone.

• B-tree block storage — xdb format uses B-tree-like block indexing to enable binary search of 100M+ IP ranges without loading entire file into memory; understanding block boundaries is critical for implementing new language bindings
• Vector index (vIndex) caching — Fixed 512KiB memory cache of IP range boundaries enables sub-100μs queries by eliminating one disk seek; this memory-latency tradeoff is unique to ip2region's architecture
• IP address integer conversion — IPv4/IPv6 addresses must be converted to integers for binary range comparisons in xdb; endianness and bit-width issues cause silent wrong-region results if implemented incorrectly
• Data compression and deduplication in xdb generation — xdb format automatically merges adjacent IP ranges with identical region data, reducing file size from ~100MB raw to ~10MB xdb; understanding this is essential before building custom xdb files
• CRC32 checksumming for data integrity — All xdb files include trailing CRC32 hash; corrupted xdb files fail validation silently, causing queries to return wrong regions—must validate before production deployment
• Memory-mapped file I/O — Some bindings (esp. C/C++) use mmap() for xdb access; enables OS-level paging and reduces latency vs explicit read() syscalls for disk-based queries
• Unified query interface across IPv4 and IPv6 — All language bindings implement single Searcher class that handles both IPv4 and IPv6 transparently; design pattern avoids code duplication but requires careful address-family detection in searcher implementation

• maxmind/geoip2-go — Alternative Go IP geolocation library using MaxMind GeoIP2 databases; ip2region competes on latency (10μs vs network roundtrip) and offline operation
• torvalds/linux — Not a direct competitor, but kernel xt_geoip and similar modules implement IP-based routing; ip2region provides userspace equivalent with richer metadata
• db-ip/dbip — Commercial IP geolocation database provider; ip2region is self-hosted alternative with custom extensibility via xdb framework instead of vendor lock-in
• oschina/ip2region — Appears to be original repository under different owner; may be community fork or historical upstream if this is mirror—check git history
• alibaba/sentinel-golang — Alibaba library for traffic flow control; uses IP geolocation for regional rate limiting—natural consumer of ip2region's low-latency lookups

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive GitHub Actions CI workflow for multi-language bindings

The repo supports 8+ language bindings (C, C++, Go, C#, Cangjie, etc.) but there's no visible CI pipeline to validate builds and tests across all bindings. This is critical for a data library where correctness across languages is paramount. A matrix-based workflow would catch binding-specific regressions early.

• [ ] Create .github/workflows/ci.yml with matrix strategy for: c (gcc/clang), cpp (g++/clang++), golang (1.18+), csharp (net6.0+), cangjie
• [ ] Add build steps for each binding referencing their Makefile or project files (e.g., binding/c/Makefile, binding/cpp/Makefile, binding/golang, binding/csharp/*.csproj)
• [ ] Include test execution steps from each binding's test directory (binding/*/test or */test.cc patterns)
• [ ] Add conditional steps to validate xdb data files exist (data/ip2region_v4.xdb, data/ip2region_v6.xdb) before test runs

Add integration tests comparing IPv4 and IPv6 query results across language bindings

The repo claims 10-microsecond query efficiency and IPv4/IPv6 parity, but there are no cross-language validation tests. A new contributor could create a test suite that validates the same IP queries return identical results across C, C++, Go, C#, and Cangjie bindings to ensure correctness.

• [ ] Create binding/tests/integration/ directory with test data file (e.g., test_ips.json containing sample IPv4 and IPv6 addresses with expected region outputs)
• [ ] Write a test harness in Go (since binding/golang exists and is portable) that shells out to test executables from binding/c/test, binding/cpp/test/search.cc, binding/csharp, etc.
• [ ] Add validation logic comparing JSON output from each binding for the same IP inputs to ensure regional data consistency
• [ ] Document test execution in binding/tests/integration/README.md with setup instructions for each binding dependency

Add missing C# binding documentation and examples for xdb searcher pool configuration

The C# binding directory (binding/csharp/) shows test files and benchmarks exist, but there's no binding/csharp/README.md like other bindings (C, C++, Cangjie all have README.md and README_zh.md). The file structure suggests searcher_pool configuration exists (analogous to cangjie/src/service/searcher_pool.cj) but is undocumented.

• [ ] Create binding/csharp/README.md documenting: basic usage, xdb file setup, IP query syntax, and searcher pool configuration (reference binding/cangjie/README.md and binding/cpp/README.md as templates)
• [ ] Create binding/csharp/README_zh.md with Chinese translations for parity with other bindings
• [ ] Add binding/csharp/examples/ directory with at least 2 example programs: (1) single IP query, (2) batch query with searcher pool to demonstrate performance
• [ ] Reference the benchmark file (binding/csharp/IP2Region.Net.BenchMark/Benmarks.cs) in documentation with expected performance metrics

• Add integration tests for xdb cross-language consistency: Write a test harness (binding/test_all.sh) that queries the same 100 IPs via searchers in all 12 languages and asserts identical results. Currently each binding has isolated unit tests (binding/*/src/tests/), but no validation that Java searcher returns same city for 8.8.8.8 as Go searcher. Start by: inspect binding/golang/main.go and binding/java/**/Example.java test patterns, then create a shared test IP list and orchestrate cross-language queries.
• Document xdb binary format specification: Create binding/XDB_FORMAT.md describing: header layout (version, check fields, block index offset), vIndex structure (512 offsets), B-tree block format (entry pairs), region string table. Extract spec from binding/c/xdb_searcher.c (most readable) and binding/golang/xdb_util.go (bit-packing details). Target: developers implementing a 13th language binding should understand format without reading all 12 searcher implementations.
• Add Rust binding test for IPv6 edge cases: binding/rust/ is listed but binding/rust/src/tests/ appears absent or minimal. Implement tests for: IPv6 address parsing (IPv4-mapped ::ffff:x.x.x.x), loopback (::1), all-zeros (::), and private ranges (fc00::/7). Compare results against binding/golang/ IPv6 tests to ensure parity. This catches xdb format bugs that only appear at IPv6 boundaries and prevents silent wrong results for growing IPv6 traffic.

• Low · Outdated Go Module Dependency — binding/golang/go.mod. The golang binding depends on github.com/mitchellh/go-homedir v1.1.0, which was last updated in 2016. While this is a utility library with minimal security surface, it should be regularly reviewed for any known vulnerabilities and updated if newer versions are available. Fix: Run 'go list -u -m all' to check for available updates. Update to the latest version of github.com/mitchellh/go-homedir and perform security auditing with 'go list -json -m all | nancy sleuth' or similar tools.
• Medium · Missing Input Validation in IP Parsing — binding/c/xdb_searcher.c, binding/cpp/src/search.cc, binding/cpp/src/ip.cc. The codebase handles IP addresses across multiple languages (C, C++, C#, Go, Cangjie). Without visible input validation in the file structure, there's potential risk of malformed IP addresses being processed, leading to buffer overflows or integer underflows in compiled bindings (C/C++), or logic errors in interpreted languages. Fix: Implement strict input validation for all IP address parsing. For C/C++ bindings, use bounds checking and safe string functions. Validate IPv4 addresses (0.0.0.0 to 255.255.255.255) and IPv6 addresses before processing.
• Medium · Potential Memory Safety Issues in C Bindings — binding/c/xdb_searcher.c, binding/c/xdb_util.c, binding/c/main.c. The C binding implementation (binding/c/) uses manual memory management which is prone to buffer overflows, use-after-free, and memory leaks. Without visible memory sanitizer configurations or comprehensive bounds checking in the analyzed files, there's elevated risk. Fix: Implement comprehensive bounds checking. Use AddressSanitizer (ASAN) and Valgrind during testing. Consider using safer alternatives like memmove_s instead of strcpy/memcpy. Add extensive unit tests for edge cases.
• Low · No Visible Security Configuration in C++ Makefile — binding/cpp/Makefile. The C++ binding Makefile doesn't show visible security compilation flags like -fstack-protector-strong, -D_FORTIFY_SOURCE=2, or -fPIE which would provide additional runtime protections against common C++ vulnerabilities. Fix: Add security-hardening compiler flags: -fstack-protector-strong, -D_FORTIFY_SOURCE=2, -fPIE, -Wl,-z,relro, -Wl,-z,now. Enable compiler warnings like -Wall, -Wextra, -Wpedantic.
• Low · Missing Dependency Lock Files for Multiple Languages — binding/csharp/IP2Region.Net.csproj, binding/cangjie/cjpm.toml. While golang has go.mod, the C#, C++, Cangjie, and C bindings may have implicit dependency management. The C# project (IP2Region.Net) appears to use package managers but lock files are not visible in the provided structure. Fix: Ensure all package managers lock dependencies. For C#, maintain packages.lock.json. For Cangjie, verify cjpm.toml locks versions. Use dependency scanning tools to identify vulnerable transitive dependencies.
• Low · No Visible Security Headers or HTTPS Configuration — README.md. The project documentation references a website (https://ip2region.net) but no visible configuration for security headers, CORS policies, or secure communication protocols in the codebase. Fix: If this library is distributed through a web service, implement security headers (HSTS, X-Content-Type-Options, CSP). Use HTTPS/TLS exclusively. Implement rate limiting and DDoS protections.
• Low · Test Files May Expose Sensitive Patterns — binding/cangjie/src/tests/, binding/csharp/IP2Region.Net.. Test files across multiple bindings (binding/cangjie/src/tests/, binding/csharp/IP2Region.Net.Test/) may contain hardcoded test IPs or patterns that could be exploited if test coverage includes edge cases or bypass scenarios. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.