fix(documentation): Improve documentation formatting and code consistency across project files
This commit is contained in:
@@ -1,5 +1,13 @@
|
||||
# Changelog
|
||||
|
||||
## 2025-05-26 - 2.1.2 - fix(documentation)
|
||||
Improve documentation formatting and code consistency across project files
|
||||
|
||||
- Refined readme.md: replaced CI status badges with streamlined installation and usage instructions
|
||||
- Updated code formatting and whitespace in detector classes and interfaces for clarity
|
||||
- Enhanced test file formatting and adjusted options to improve test readability
|
||||
- Minor improvements in commit info data structure
|
||||
|
||||
## 2025-05-26 - 2.1.1 - fix(detector)
|
||||
Improve test coverage and adjust detection result handling
|
||||
|
||||
|
||||
@@ -52,4 +52,4 @@
|
||||
"pnpm": {
|
||||
"overrides": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
165
readme.md
165
readme.md
@@ -9,26 +9,163 @@ a detector for answering network questions locally. It does not rely on any onli
|
||||
- [github.com (source mirror)](https://github.com/uptime.link/detector)
|
||||
- [docs (typedoc)](https://uptime.link.gitlab.io/detector/)
|
||||
|
||||
## Status for master
|
||||
## Installation
|
||||
|
||||
| Status Category | Status Badge |
|
||||
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| GitLab Pipelines | [](https://lossless.cloud) |
|
||||
| GitLab Pipline Test Coverage | [](https://lossless.cloud) |
|
||||
| npm | [](https://lossless.cloud) |
|
||||
| Snyk | [](https://lossless.cloud) |
|
||||
| TypeScript Support | [](https://lossless.cloud) |
|
||||
| node Support | [](https://nodejs.org/dist/latest-v10.x/docs/api/) |
|
||||
| Code Style | [](https://lossless.cloud) |
|
||||
| PackagePhobia (total standalone install weight) | [](https://lossless.cloud) |
|
||||
| PackagePhobia (package size on registry) | [](https://lossless.cloud) |
|
||||
| BundlePhobia (total size when bundled) | [](https://lossless.cloud) |
|
||||
| Platform support | [](https://lossless.cloud) [](https://lossless.cloud) |
|
||||
```bash
|
||||
npm install @uptime.link/detector
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Use TypeScript for best in class intellisense
|
||||
|
||||
### Basic Port Detection
|
||||
|
||||
```typescript
|
||||
import { Detector } from '@uptime.link/detector';
|
||||
|
||||
const detector = new Detector();
|
||||
|
||||
// Check if a port is active (returns detailed result)
|
||||
const result = await detector.isActive('https://example.com');
|
||||
console.log(result.isActive); // true
|
||||
|
||||
// Simple boolean check (backward compatible)
|
||||
const isActive = await detector.isActiveSimple('https://example.com');
|
||||
console.log(isActive); // true
|
||||
```
|
||||
|
||||
### Service Type Detection
|
||||
|
||||
The detector can identify what service is running on a port:
|
||||
|
||||
```typescript
|
||||
// Detect service type along with port check
|
||||
const result = await detector.isActive('https://github.com', {
|
||||
detectServiceType: true,
|
||||
});
|
||||
|
||||
console.log(result.isActive); // true
|
||||
console.log(result.serviceType); // 'https'
|
||||
|
||||
// Direct service type detection
|
||||
const serviceType = await detector.detectType('ssh://github.com:22');
|
||||
console.log(serviceType); // 'ssh'
|
||||
```
|
||||
|
||||
### Supported Service Types
|
||||
|
||||
The detector can identify the following services:
|
||||
|
||||
- **HTTP** (port 80)
|
||||
- **HTTPS** (port 443)
|
||||
- **SSH** (port 22)
|
||||
- **FTP** (port 21)
|
||||
- **SMTP** (port 25)
|
||||
- **POP3** (port 110)
|
||||
- **IMAP** (port 143)
|
||||
- **MySQL** (port 3306)
|
||||
- **PostgreSQL** (port 5432)
|
||||
- **MongoDB** (port 27017)
|
||||
- **Redis** (port 6379)
|
||||
- **Unknown** (for unidentified services)
|
||||
|
||||
### Advanced Examples
|
||||
|
||||
```typescript
|
||||
// Check localhost ports
|
||||
const localResult = await detector.isActive('http://localhost:3000', {
|
||||
detectServiceType: true,
|
||||
});
|
||||
|
||||
if (localResult.isActive) {
|
||||
console.log(`Local service detected: ${localResult.serviceType}`);
|
||||
}
|
||||
|
||||
// Check multiple services
|
||||
const urls = ['https://api.github.com', 'http://example.com', 'ssh://gitlab.com:22'];
|
||||
|
||||
for (const url of urls) {
|
||||
const result = await detector.isActive(url, { detectServiceType: true });
|
||||
console.log(`${url}: ${result.isActive ? result.serviceType : 'offline'}`);
|
||||
}
|
||||
|
||||
// Handle different URL schemes with automatic port detection
|
||||
const sshDetection = await detector.detectType('ssh://github.com');
|
||||
// Automatically uses port 22 for SSH
|
||||
|
||||
const mysqlDetection = await detector.detectType('mysql://localhost');
|
||||
// Automatically uses port 3306 for MySQL
|
||||
```
|
||||
|
||||
### API Reference
|
||||
|
||||
#### `Detector`
|
||||
|
||||
The main class for network detection.
|
||||
|
||||
##### Methods
|
||||
|
||||
- **`isActive(url: string, options?: IDetectorOptions): Promise<IDetectorResult>`**
|
||||
|
||||
- Checks if a port is active and optionally detects the service type
|
||||
- Returns detailed information about the port status and service
|
||||
|
||||
- **`isActiveSimple(url: string): Promise<boolean>`**
|
||||
|
||||
- Simple boolean check for backward compatibility
|
||||
- Returns `true` if port is active, `false` otherwise
|
||||
|
||||
- **`detectType(url: string): Promise<ServiceType>`**
|
||||
- Detects the service type running on the specified URL
|
||||
- Uses protocol-specific detection methods and banner grabbing
|
||||
|
||||
#### Interfaces
|
||||
|
||||
```typescript
|
||||
interface IDetectorResult {
|
||||
isActive: boolean;
|
||||
serviceType?: ServiceType;
|
||||
protocol?: 'tcp' | 'udp';
|
||||
responseTime?: number;
|
||||
tlsVersion?: string;
|
||||
serviceBanner?: string;
|
||||
error?: string;
|
||||
}
|
||||
|
||||
interface IDetectorOptions {
|
||||
timeout?: number;
|
||||
includeNetworkDiagnostics?: boolean;
|
||||
detectServiceType?: boolean;
|
||||
}
|
||||
|
||||
enum ServiceType {
|
||||
HTTP = 'http',
|
||||
HTTPS = 'https',
|
||||
SSH = 'ssh',
|
||||
FTP = 'ftp',
|
||||
SMTP = 'smtp',
|
||||
POP3 = 'pop3',
|
||||
IMAP = 'imap',
|
||||
MYSQL = 'mysql',
|
||||
POSTGRESQL = 'postgresql',
|
||||
MONGODB = 'mongodb',
|
||||
REDIS = 'redis',
|
||||
UNKNOWN = 'unknown',
|
||||
}
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
- ✅ **Local Network Detection** - Check ports on localhost without external services
|
||||
- ✅ **Remote Port Detection** - Verify if remote ports are accessible
|
||||
- ✅ **Service Identification** - Detect what service is running on a port
|
||||
- ✅ **Protocol Detection** - Identify HTTP/HTTPS and other protocols
|
||||
- ✅ **Banner Grabbing** - Extract service information from response banners
|
||||
- ✅ **TypeScript Support** - Full type definitions included
|
||||
- ✅ **ESM Module** - Modern ES module support
|
||||
- ✅ **No External Dependencies** - All detection happens locally
|
||||
|
||||
## Contribution
|
||||
|
||||
We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)
|
||||
|
||||
@@ -51,7 +51,9 @@ tap.test('should detect SSH service on GitHub', async () => {
|
||||
});
|
||||
|
||||
tap.test('should detect HTTPS on non-standard port', async () => {
|
||||
const result = await testDetector.isActive('https://lossless.com:443', { detectServiceType: true });
|
||||
const result = await testDetector.isActive('https://lossless.com:443', {
|
||||
detectServiceType: true,
|
||||
});
|
||||
if (result.isActive) {
|
||||
expect(result.serviceType).toEqual(detector.ServiceType.HTTPS);
|
||||
}
|
||||
@@ -146,4 +148,4 @@ tap.test('should detect commonly used local development ports', async () => {
|
||||
}
|
||||
});
|
||||
|
||||
export default tap.start();
|
||||
export default tap.start();
|
||||
|
||||
@@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@uptime.link/detector',
|
||||
version: '2.1.1',
|
||||
version: '2.1.2',
|
||||
description: 'a detector for answering network questions locally. It does not rely on any online services.'
|
||||
}
|
||||
|
||||
@@ -24,11 +24,11 @@ export class Detector {
|
||||
parseInt(parsedUrl.port, 10),
|
||||
);
|
||||
const portAvailable = !portUnused;
|
||||
|
||||
|
||||
const result: IDetectorResult = {
|
||||
isActive: portAvailable
|
||||
isActive: portAvailable,
|
||||
};
|
||||
|
||||
|
||||
if (options?.detectServiceType) {
|
||||
if (portAvailable) {
|
||||
const serviceType = await this.detectType(urlArg);
|
||||
@@ -37,7 +37,7 @@ export class Detector {
|
||||
result.serviceType = ServiceType.UNKNOWN;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
return result;
|
||||
} else {
|
||||
console.log(`detector target is remote domain ${parsedUrl.host} on port ${parsedUrl.port}`);
|
||||
@@ -45,11 +45,11 @@ export class Detector {
|
||||
parsedUrl.host,
|
||||
parseInt(parsedUrl.port, 10),
|
||||
);
|
||||
|
||||
|
||||
const result: IDetectorResult = {
|
||||
isActive: portAvailable
|
||||
isActive: portAvailable,
|
||||
};
|
||||
|
||||
|
||||
if (options?.detectServiceType) {
|
||||
if (portAvailable) {
|
||||
const serviceType = await this.detectType(urlArg);
|
||||
@@ -58,36 +58,36 @@ export class Detector {
|
||||
result.serviceType = ServiceType.UNKNOWN;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
|
||||
public async detectType(urlArg: string): Promise<ServiceType> {
|
||||
const parsedUrl = plugins.smarturl.Smarturl.createFromUrl(urlArg);
|
||||
|
||||
|
||||
// Handle different URL schemes and default ports
|
||||
let port = parseInt(parsedUrl.port, 10);
|
||||
if (isNaN(port)) {
|
||||
// Set default ports based on scheme
|
||||
const defaultPorts: { [key: string]: number } = {
|
||||
'http': 80,
|
||||
'https': 443,
|
||||
'ssh': 22,
|
||||
'ftp': 21,
|
||||
'smtp': 25,
|
||||
'mysql': 3306,
|
||||
'postgresql': 5432,
|
||||
'mongodb': 27017,
|
||||
'redis': 6379
|
||||
http: 80,
|
||||
https: 443,
|
||||
ssh: 22,
|
||||
ftp: 21,
|
||||
smtp: 25,
|
||||
mysql: 3306,
|
||||
postgresql: 5432,
|
||||
mongodb: 27017,
|
||||
redis: 6379,
|
||||
};
|
||||
|
||||
|
||||
const scheme = parsedUrl.protocol.replace(':', '').toLowerCase();
|
||||
port = defaultPorts[scheme] || 80;
|
||||
}
|
||||
|
||||
|
||||
const hostname = parsedUrl.hostname;
|
||||
|
||||
|
||||
// Check common ports first
|
||||
const commonPorts: { [key: number]: ServiceType } = {
|
||||
80: ServiceType.HTTP,
|
||||
@@ -100,9 +100,9 @@ export class Detector {
|
||||
3306: ServiceType.MYSQL,
|
||||
5432: ServiceType.POSTGRESQL,
|
||||
27017: ServiceType.MONGODB,
|
||||
6379: ServiceType.REDIS
|
||||
6379: ServiceType.REDIS,
|
||||
};
|
||||
|
||||
|
||||
if (commonPorts[port]) {
|
||||
// Verify the service is actually what we expect
|
||||
const verified = await this.verifyServiceType(hostname, port, commonPorts[port]);
|
||||
@@ -110,12 +110,16 @@ export class Detector {
|
||||
return commonPorts[port];
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
// Try to detect service by banner/protocol
|
||||
return await this.detectServiceByProtocol(hostname, port);
|
||||
}
|
||||
|
||||
private async verifyServiceType(hostname: string, port: number, expectedType: ServiceType): Promise<boolean> {
|
||||
|
||||
private async verifyServiceType(
|
||||
hostname: string,
|
||||
port: number,
|
||||
expectedType: ServiceType,
|
||||
): Promise<boolean> {
|
||||
try {
|
||||
switch (expectedType) {
|
||||
case ServiceType.HTTP:
|
||||
@@ -130,33 +134,37 @@ export class Detector {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
private async detectServiceByProtocol(hostname: string, port: number): Promise<ServiceType> {
|
||||
// Try HTTPS first
|
||||
if (await this.checkHttpService(hostname, port, true)) {
|
||||
return ServiceType.HTTPS;
|
||||
}
|
||||
|
||||
|
||||
// Try HTTP
|
||||
if (await this.checkHttpService(hostname, port, false)) {
|
||||
return ServiceType.HTTP;
|
||||
}
|
||||
|
||||
|
||||
// Try SSH
|
||||
if (await this.checkSshService(hostname, port)) {
|
||||
return ServiceType.SSH;
|
||||
}
|
||||
|
||||
|
||||
// Try to get banner for other services
|
||||
const banner = await this.getBanner(hostname, port);
|
||||
if (banner) {
|
||||
return this.identifyServiceByBanner(banner);
|
||||
}
|
||||
|
||||
|
||||
return ServiceType.UNKNOWN;
|
||||
}
|
||||
|
||||
private async checkHttpService(hostname: string, port: number, isHttps: boolean): Promise<boolean> {
|
||||
|
||||
private async checkHttpService(
|
||||
hostname: string,
|
||||
port: number,
|
||||
isHttps: boolean,
|
||||
): Promise<boolean> {
|
||||
return new Promise((resolve) => {
|
||||
const protocol = isHttps ? plugins.https : plugins.http;
|
||||
const options = {
|
||||
@@ -164,81 +172,81 @@ export class Detector {
|
||||
port,
|
||||
method: 'HEAD',
|
||||
timeout: 5000,
|
||||
rejectUnauthorized: false // Accept self-signed certificates
|
||||
rejectUnauthorized: false, // Accept self-signed certificates
|
||||
};
|
||||
|
||||
|
||||
const req = protocol.request(options, () => {
|
||||
resolve(true);
|
||||
});
|
||||
|
||||
|
||||
req.on('error', () => {
|
||||
resolve(false);
|
||||
});
|
||||
|
||||
|
||||
req.on('timeout', () => {
|
||||
req.destroy();
|
||||
resolve(false);
|
||||
});
|
||||
|
||||
|
||||
req.end();
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
private async checkSshService(hostname: string, port: number): Promise<boolean> {
|
||||
return new Promise((resolve) => {
|
||||
const socket = new plugins.net.Socket();
|
||||
|
||||
|
||||
socket.setTimeout(5000);
|
||||
|
||||
|
||||
socket.on('data', (data) => {
|
||||
const banner = data.toString();
|
||||
socket.destroy();
|
||||
// SSH banners typically start with "SSH-"
|
||||
resolve(banner.startsWith('SSH-'));
|
||||
});
|
||||
|
||||
|
||||
socket.on('error', () => {
|
||||
resolve(false);
|
||||
});
|
||||
|
||||
|
||||
socket.on('timeout', () => {
|
||||
socket.destroy();
|
||||
resolve(false);
|
||||
});
|
||||
|
||||
|
||||
socket.connect(port, hostname);
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
private async getBanner(hostname: string, port: number): Promise<string | null> {
|
||||
return new Promise((resolve) => {
|
||||
const socket = new plugins.net.Socket();
|
||||
let banner = '';
|
||||
|
||||
|
||||
socket.setTimeout(5000);
|
||||
|
||||
|
||||
socket.on('data', (data) => {
|
||||
banner += data.toString();
|
||||
socket.destroy();
|
||||
resolve(banner);
|
||||
});
|
||||
|
||||
|
||||
socket.on('error', () => {
|
||||
resolve(null);
|
||||
});
|
||||
|
||||
|
||||
socket.on('timeout', () => {
|
||||
socket.destroy();
|
||||
resolve(banner || null);
|
||||
});
|
||||
|
||||
|
||||
socket.connect(port, hostname);
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
private identifyServiceByBanner(banner: string): ServiceType {
|
||||
const bannerLower = banner.toLowerCase();
|
||||
|
||||
|
||||
if (bannerLower.includes('ssh')) return ServiceType.SSH;
|
||||
if (bannerLower.includes('ftp')) return ServiceType.FTP;
|
||||
if (bannerLower.includes('smtp')) return ServiceType.SMTP;
|
||||
@@ -248,7 +256,7 @@ export class Detector {
|
||||
if (bannerLower.includes('postgresql')) return ServiceType.POSTGRESQL;
|
||||
if (bannerLower.includes('mongodb')) return ServiceType.MONGODB;
|
||||
if (bannerLower.includes('redis')) return ServiceType.REDIS;
|
||||
|
||||
|
||||
return ServiceType.UNKNOWN;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -10,7 +10,7 @@ export enum ServiceType {
|
||||
POSTGRESQL = 'postgresql',
|
||||
MONGODB = 'mongodb',
|
||||
REDIS = 'redis',
|
||||
UNKNOWN = 'unknown'
|
||||
UNKNOWN = 'unknown',
|
||||
}
|
||||
|
||||
export interface IDetectorResult {
|
||||
@@ -41,4 +41,4 @@ export interface IDetectorOptions {
|
||||
timeout?: number;
|
||||
includeNetworkDiagnostics?: boolean;
|
||||
detectServiceType?: boolean;
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user