# @uptime.link/detector

Documentation for @uptime.link/detector

# readme.md for @uptime.link/detector

a detector for answering network questions locally. It does not rely on any online services.

## Availabililty and Links

- [npmjs.org (npm package)](https://www.npmjs.com/package/@uptime.link/detector)
- [gitlab.com (source)](https://gitlab.com/uptime.link/detector)
- [github.com (source mirror)](https://github.com/uptime.link/detector)
- [docs (typedoc)](https://uptime.link.gitlab.io/detector/)

## Installation

```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). :)

For further information read the linked docs at the top of this readme.

> MIT licensed | **&copy;** [Lossless GmbH](https://lossless.gmbh)
> | By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)

[![repo-footer](https://lossless.gitlab.io/publicrelations/repofooter.svg)](https://maintainedby.lossless.com)

# changelog.md for @uptime.link/detector

## 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

- Updated readme hints and plan to document the enhanced comprehensive test suite
- Expanded tests to cover backward compatibility, performance benchmarks, and multiple service types
- Modified detection logic to set serviceType to UNKNOWN when a port is inactive with detectServiceType option

## 2025-05-26 - 2.1.0 - feat(detector)
Enhance port detection and service fingerprinting with improved HTTP/HTTPS and SSH checks, update test scripts for verbose output, and revise documentation with new hints and a detailed improvement plan.

- Updated package.json to use verbose testing and added '@git.zone/tsrun' dependency
- Improved Detector class: finalized detectType implementation with protocol-specific checks and banner grabbing
- Refined test cases to verify active ports and service detection for HTTP, HTTPS, and SSH
- Expanded readme hints with project overview, key components, and detailed improvement plan

## 2025-05-26 - 2.0.2 - fix(ci)
Update CI workflows, dependency paths, and project configuration

- Added new CI workflow files (.gitea/workflows/default_nottags.yaml and .gitea/workflows/default_tags.yaml) to replace the old GitLab CI configuration
- Removed obsolete .gitlab-ci.yml file
- Updated dependency import paths from '@pushrocks' to '@push.rocks' in source and commit info files
- Revised package.json with new metadata fields and updated dependency versions
- Enhanced tsconfig.json with decorator metadata and NodeNext module settings
- Minor adjustments in .gitignore and readme formatting

## 2022-07-16 - 2.0.1 - no significant changes
This release was a version update only and did not include any relevant changes.

- No noteworthy modifications.

## 2022-07-16 - 2.0.0 - core
fix(core): update

- Updated core functionality.

## 2022-07-16 - 1.0.5 - core
BREAKING CHANGE(core): switch to esm

- Switched to ES modules, introducing breaking changes.

## 2022-07-16 - 1.0.4 - core
fix(core): update

- Updated core functionality.

## 2021-04-14 - 1.0.3 - core
fix(core): update

- Updated core functionality.

## 2021-04-13 - 1.0.2 - core
fix(core): update

- Updated core functionality.

## 2021-04-12 - 1.0.1 - core
fix(core): update

- Updated core functionality.

Other releases that were simple version bumps have been omitted from detailed descriptions.