mirror of
https://github.com/Xevion/rdap.git
synced 2025-12-05 23:15:58 -06:00
docs: add comprehensive README with screenshots and feature documentation
- Add domain and IPv4 query screenshots to .media/ - Expand README with detailed feature list, installation guide, and architecture overview - Add badges for version, license, CI, codecov, TypeScript, Next.js, and React - Document RDAP protocol explanation, query capabilities, and supported entity types - Include dark mode feature, shareable links, and self-hosting instructions - Update copyright year to 2025 in LICENSE
This commit is contained in:
BIN
.media/domain.png
Normal file
BIN
.media/domain.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
BIN
.media/ipv4.png
Normal file
BIN
.media/ipv4.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
2
LICENSE
2
LICENSE
@@ -1,6 +1,6 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2023 Ryan Walters
|
||||
Copyright (c) 2025 Ryan Walters
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
|
||||
222
README.md
222
README.md
@@ -1,47 +1,203 @@
|
||||
# rdap
|
||||
|
||||
A private RDAP query client built with React & Next.js.
|
||||
[![Version][badge-version]][npm]
|
||||
[![License][badge-license]][license]
|
||||
[![CI][badge-ci]][ci-workflow]
|
||||
[![Codecov][badge-codecov]][codecov]
|
||||
[![TypeScript][badge-typescript]][typescript]
|
||||
[![Next.js][badge-nextjs]][nextjs]
|
||||
[![React][badge-react]][react]
|
||||
|
||||
## Usage
|
||||
[badge-version]: https://img.shields.io/badge/version-0.2.0-blue
|
||||
[badge-license]: https://img.shields.io/badge/license-MIT-green
|
||||
[badge-ci]: https://github.com/Xevion/rdap/actions/workflows/ci.yml/badge.svg
|
||||
[badge-codecov]: https://codecov.io/gh/Xevion/rdap/branch/master/graph/badge.svg
|
||||
[badge-typescript]: https://img.shields.io/badge/TypeScript-5.9-blue
|
||||
[badge-nextjs]: https://img.shields.io/badge/Next.js-15.5-black
|
||||
[badge-react]: https://img.shields.io/badge/React-19.2-blue
|
||||
|
||||
This project uses [Next.js][nextjs] (SSG only) and React. Install [Node.js][nodejs] and [Yarn][yarn], then run the following commands:
|
||||
A modern RDAP query client built with Next.js and React. Query domains, IP addresses, ASNs, and more. Now with **dark mode**.
|
||||
|
||||
```bash
|
||||
# install dependencies
|
||||
yarn
|
||||
# run the development server
|
||||
yarn dev
|
||||
# or build and run the production server
|
||||
yarn build && yarn start
|
||||
```
|
||||
[][live-demo]
|
||||
[][live-demo]
|
||||
|
||||
The project is also hosted on [my website][rdap].
|
||||
> [!TIP]
|
||||
> **Try the live demo at [rdap.xevion.dev][live-demo]** to query domains, IPs, ASNs, and more in real-time.
|
||||
|
||||
## What is RDAP?
|
||||
|
||||
RDAP (Registration Data Access Protocol) is the modern successor to WHOIS, providing structured, machine-readable access to domain registration and network resource data. Instead of parsing inconsistent text output, RDAP delivers standardized JSON responses with richer metadata.
|
||||
|
||||
## Why?
|
||||
|
||||
Built for personal use, this project is an RDAP client; a tool that lets you execute RDAP queries on any entities that are associated with an RDAP server.
|
||||
In more simpler terms, it's a tool that lets you look up information about IP addresses, domain names, and autonomous systems (a network of controlled IP addresses), and a little more.
|
||||
The tool hosted by [rdap.org][rdap-client] is fantastic, but it's too simple, and isn't as overly-complicated and annoying as I want it to be. So, I built my own. **Mine has dark mode.**
|
||||
|
||||
The tool hosted by [rdap.org](https://client.rdap.org) is fantastic, but it's too simple, and isn't as overly-complicated and annoying as I want it to be. So, I built my own. Mine has dark mode.
|
||||
Inspired by the [rdap.org client][rdap-client], this project adds several features I wanted:
|
||||
|
||||
But in all seriousness, my project does intend to have more features:
|
||||
- **🌙 Dark Mode**: Because the blistering white of other RDAP clients is painful to look at
|
||||
- **🔗 Shareable Links**: Every query generates a unique URL you can bookmark or share
|
||||
- **🎨 Modern Interface**: Intuitive type detection, status badges, and responsive design
|
||||
- **📊 Rich Data Display**: Comprehensive support for all RDAP entity types, DNSSEC, JSContact, vCard, and more
|
||||
- **⚡ Advanced Features**: Follow referrals to registrars, modern JSContact format support, export/copy JSON responses
|
||||
- **🏠 Self-Hostable**: Static site that you can deploy anywhere for complete control
|
||||
|
||||
- Proxying: Some RDAP servers are inaccessible over the browser, and so proxying requests through a server is necessary.
|
||||
- Self Hosting: For those worried about privacy, the project can be self-hosted.
|
||||
- No Tracking: The project can't track you, because it's a static site. And in terms of the proxy, you can self-host if you're worried about that.
|
||||
- Better UI: I'm not a designer, but I can try.
|
||||
- Dark Mode: The blistering white of the original RDAP client is painful to look at.
|
||||
- Shareable Links: Each search produces a unique URL that can be shared with others to view the same query.
|
||||
- Whois: RDAP is a newer protocol that is meant to replace Whois, but some servers still use Whois. I might add support for that.
|
||||
- Punycode: Some domain names use punycode, which is a way to represent Unicode characters in ASCII. I might add support for working with these domains.
|
||||
- Better Error Handling: The original RDAP client doesn't handle errors very well, or tell you what went wrong. I want to fix that.
|
||||
- For example, when querying a TLD that does not have a RDAP server, or one that does not exist, the original client doesn't explain this very well.
|
||||
- RDAP Schema Adherence: RDAP servers are supposed to follow a schema, but it appears a large number simply don't. I intend to provide handling for this.
|
||||
- Essentially, two separate schemas will be available: one for basic type checking, and one for the RFC-compliant schema.
|
||||
- If the server doesn't follow the RFC-compliant schema, the basic schema will be used instead.
|
||||
- It's hard to tell at this moment if Typescript can handle this well, but I'll try.
|
||||
## Features
|
||||
|
||||
[rdap]: https://rdap.xevion.dev
|
||||
[nextjs]: https://nextjs.org
|
||||
### Query Capabilities
|
||||
|
||||
- **Multiple Input Types**: IPv4/IPv6 (with CIDR notation), domain names, TLDs, ASNs, entity handles, or raw RDAP URLs
|
||||
- **Smart Auto-Detection**: Automatically identifies query types with visual feedback
|
||||
- **Manual Override**: Lock query type when auto-detection isn't enough
|
||||
- **Follow Referrals**: Automatically follows redirects to registrar RDAP servers for complete data
|
||||
- **JSContact Support**: Modern JSContact (RFC 9553) format alongside traditional vCard
|
||||
|
||||
### Supported Entity Types
|
||||
|
||||
Full rendering support for all RDAP object classes:
|
||||
|
||||
- **Domains**: Name, status, nameservers, DNSSEC, registrar info, creation/expiry dates
|
||||
- **IP Networks**: IPv4/IPv6 ranges, allocation dates, network types, parent/child relationships
|
||||
- **Autonomous Systems**: AS numbers, names, registration details
|
||||
- **Entities**: Contacts, registrars, registrants with role information and public IDs
|
||||
- **Nameservers**: Hostnames with IPv4/IPv6 address mappings
|
||||
|
||||
### Contact Information
|
||||
|
||||
- **Dual Format Support**: Both legacy vCard (jCard) and modern JSContact (RFC 9553)
|
||||
- **Rich Contact Data**: Names, organizations, emails, phone numbers, addresses, URLs, titles, and roles
|
||||
- **Structured Display**: Clean presentation of hierarchical contact information
|
||||
|
||||
### DNS Security (DNSSEC)
|
||||
|
||||
- Zone signing and delegation status indicators
|
||||
- DS (Delegation Signer) records with key tags, algorithms, digest types
|
||||
- DNSKEY records with flags, protocols, and public keys
|
||||
- Maximum signature lifetime display
|
||||
|
||||
### User Experience
|
||||
|
||||
- **🎨 Theme Toggle**: Full dark mode and light mode support with persistence
|
||||
- **📋 Data Export**: Copy individual values, entire JSON responses, or download as files
|
||||
- **🔍 Raw View Toggle**: Switch between formatted display and raw JSON
|
||||
- **📊 Status Badges**: Interactive badges for 28+ RDAP status types with hover definitions
|
||||
- **⏱️ Relative Timestamps**: Human-readable event times with precise date fallback
|
||||
- **📱 Responsive Design**: Mobile-first layout that adapts from phone to desktop
|
||||
|
||||
### Error Handling & Validation
|
||||
|
||||
- **Comprehensive HTTP Error Messages**: Clear explanations for 302, 400, 403, 404, 500 responses
|
||||
- **Input Validation**: Type checking with helpful warnings when manual type doesn't match input
|
||||
- **Schema Validation**: Zod-based validation with readable error messages
|
||||
- **Bootstrap Integration**: Automatic IANA registry bootstrap for URL resolution
|
||||
|
||||
### Technical Details
|
||||
|
||||
- **Registry Bootstrap**: Automatic fetching from IANA bootstrap files (DNS, IPv4, IPv6, ASN, object tags)
|
||||
- **CIDR Matching**: Proper network range matching for IP lookups
|
||||
- **Internationalization**: Full Unicode domain name support
|
||||
- **Type Safety**: Comprehensive TypeScript types inferred from Zod schemas
|
||||
- **Static Site**: No backend required for basic usage, fully client-side queries
|
||||
|
||||
## Installation & Usage
|
||||
|
||||
This project uses [pnpm][pnpm] as its package manager. Make sure you have [Node.js][nodejs] installed, then run:
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Run development server
|
||||
pnpm dev
|
||||
|
||||
# Build for production
|
||||
pnpm build
|
||||
|
||||
# Start production server
|
||||
pnpm start
|
||||
```
|
||||
|
||||
The development server will be available at `http://localhost:3000`.
|
||||
|
||||
### Additional Commands
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
pnpm test
|
||||
|
||||
# Run tests with UI
|
||||
pnpm test:ui
|
||||
|
||||
# Type checking
|
||||
pnpm type-check
|
||||
|
||||
# Linting
|
||||
pnpm lint
|
||||
pnpm lint:fix
|
||||
|
||||
# Code formatting
|
||||
pnpm format
|
||||
pnpm format:check
|
||||
```
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **[Next.js 15][nextjs]**: React framework with static site generation (SSG only)
|
||||
- **[React 19][react]**: UI library with modern hooks
|
||||
- **[TypeScript 5.9][typescript]**: Type-safe development
|
||||
- **[Radix UI Themes][radix]**: Accessible component primitives and design system
|
||||
- **[Tailwind CSS 4][tailwind]**: Utility-first styling
|
||||
- **[Zod 4][zod]**: Runtime schema validation
|
||||
- **[Vitest][vitest]**: Fast unit testing framework
|
||||
- **[next-themes][next-themes]**: Theme management
|
||||
|
||||
## Self-Hosting
|
||||
|
||||
This is a **fully static site** with no backend required for basic usage. It generates all HTML at build time and queries RDAP servers directly from your browser.
|
||||
|
||||
**Key characteristics**:
|
||||
|
||||
- ✅ All RDAP queries made directly from your browser to source servers
|
||||
- ✅ No intermediary servers logging your lookups
|
||||
- ✅ Minimal local storage (theme preference only)
|
||||
- ✅ Fully self-hostable for complete control
|
||||
|
||||
**Note on CORS**: Some RDAP servers don't enable CORS headers, preventing direct browser access. For these servers, you'll see an error. Future versions may include an optional proxy for these cases.
|
||||
|
||||
To self-host:
|
||||
|
||||
```bash
|
||||
# Build the static site
|
||||
pnpm build
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
Issues and pull requests are welcome! This project uses:
|
||||
|
||||
- **ESLint** for linting
|
||||
- **Prettier** for code formatting
|
||||
- **Husky** for git hooks
|
||||
- **Conventional Commits** for commit messages
|
||||
|
||||
## License
|
||||
|
||||
[MIT License][license] © 2025 Ryan Walters
|
||||
|
||||
<!-- Links -->
|
||||
|
||||
[live-demo]: https://rdap.xevion.dev
|
||||
[rdap-client]: https://client.rdap.org
|
||||
[ci-workflow]: https://github.com/Xevion/rdap/actions/workflows/ci.yml
|
||||
[codecov]: https://codecov.io/gh/Xevion/rdap
|
||||
[pnpm]: https://pnpm.io/
|
||||
[nodejs]: https://nodejs.org
|
||||
[yarn]: https://yarnpkg.com
|
||||
[nextjs]: https://nextjs.org
|
||||
[react]: https://react.dev
|
||||
[typescript]: https://www.typescriptlang.org
|
||||
[radix]: https://www.radix-ui.com
|
||||
[tailwind]: https://tailwindcss.com
|
||||
[zod]: https://zod.dev
|
||||
[vitest]: https://vitest.dev
|
||||
[next-themes]: https://github.com/pacocoursey/next-themes
|
||||
[license]: LICENSE
|
||||
[npm]: https://www.npmjs.com/package/rdap
|
||||
|
||||
Reference in New Issue
Block a user