<div align="center">

<!-- <img src="https://raw.githubusercontent.com/al8n/agnostic/main/art/logo.png" height = "200px"> -->

<h1>Agnostic</h1>

</div>
<div align="center">

`agnostic` is an agnostic abstraction layer for any async runtime.

If you want a light weight crate, see `agnostic-lite`.

[<img alt="github" src="https://img.shields.io/badge/github-al8n/agnostic-8da0cb?style=for-the-badge&logo=Github" height="22">][Github-url]
<img alt="LoC" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2Fal8n%2F327b2a8aef9003246e45c6e47fe63937%2Fraw%2Fagnostic" height="22">
[<img alt="Build" src="https://img.shields.io/github/actions/workflow/status/al8n/agnostic/ci.yml?logo=Github-Actions&style=for-the-badge" height="22">][CI-url]
[<img alt="codecov" src="https://img.shields.io/codecov/c/gh/al8n/agnostic?style=for-the-badge&token=6R3QFWRWHL&logo=codecov" height="22">][codecov-url]

[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-agnostic-66c2a5?style=for-the-badge&labelColor=555555&logo=data:image/svg+xml;base64, " height="20">][doc-url]
[<img alt="crates.io" src="https://img.shields.io/crates/v/agnostic?style=for-the-badge&logo=data:image/svg+xml;base64, " height="22">][crates-url]
[<img alt="crates.io" src="https://img.shields.io/crates/d/agnostic?color=critical&logo=data:image/svg+xml;base64, &style=for-the-badge" height="22">][crates-url]
<img alt="license" src="https://img.shields.io/badge/License-Apache%202.0/MIT-blue.svg?style=for-the-badge&fontColor=white&logoColor=f5c076&logo=data:image/svg+xml;base64, " height="22">

</div>

## Introduction

`agnostic` is a comprehensive, runtime-agnostic abstraction layer for async Rust. It provides a unified API for task spawning, networking, DNS resolution, process management, and QUIC protocol support - all working seamlessly with tokio, or smol.

**Looking for a lightweight option?** Check out [`agnostic-lite`](../agnostic-lite/) for a minimal, `no_std`-compatible core.

## Features

- **Task Management**: Spawn tasks globally or locally
- **Time Operations**: Sleep, intervals, timeouts, and delays
- **Networking**: TCP listeners/streams and UDP sockets
- **DNS Resolution**: Multiple transports (DoH, DoT, DoQ, DoH3) with DNSSEC
- **Process Management**: Spawn and manage subprocesses
- **QUIC Support**: Quinn protocol integration
- **Runtime Agnostic**: Switch runtimes with a single feature flag
- **Zero-Cost**: Compiles to runtime-specific code

## Installation

```toml
[dependencies]
agnostic = "0.9"
```

### Runtime Selection

Choose one runtime feature:

```toml
# For tokio
agnostic = { version = "0.9", features = ["tokio"] }

# For smol
agnostic = { version = "0.9", features = ["smol"] }
```

### Optional Features

```toml
# Enable networking
agnostic = { version = "0.9", features = ["tokio", "net"] }

# Enable DNS resolution
agnostic = { version = "0.9", features = ["tokio", "dns"] }

# Enable DNS over HTTPS (ring crypto)
agnostic = { version = "0.9", features = ["tokio", "https-ring"] }

# Enable DNS over QUIC (ring crypto)
agnostic = { version = "0.9", features = ["tokio", "quic-ring"] }

# Enable DNSSEC
agnostic = { version = "0.9", features = ["tokio", "dnssec-ring"] }

# Enable process management
agnostic = { version = "0.9", features = ["tokio", "process"] }

# Enable Quinn QUIC
agnostic = { version = "0.9", features = ["tokio", "quinn"] }
```

## Feature Flags

### Core Features

- `std` (default): Standard library support
- `alloc`: Allocation support

### Runtime Features (choose one)

- `tokio`: Tokio runtime support
- `smol`: Smol runtime support

### Component Features

- `net`: Network abstractions (TCP, UDP)
- `dns`: DNS resolution support
- `process`: Process spawning and management
- `quinn`: Quinn QUIC protocol support
- `tokio-io`: Tokio I/O trait compatibility

### DNS Transport Features

Each transport protocol requires a crypto backend choice (`ring` or `aws-lc-rs`):

- `tls-ring` / `tls-aws-lc-rs`: DNS over TLS
- `https-ring` / `https-aws-lc-rs`: DNS over HTTPS
- `quic-ring` / `quic-aws-lc-rs`: DNS over QUIC (RFC 9250)
- `h3-ring` / `h3-aws-lc-rs`: DNS over HTTP/3
- `webpki-roots`: Use webpki root certificates
- `rustls-platform-verifier`: Use platform certificate verifier

### DNSSEC Features

- `dnssec-ring`: DNSSEC with ring crypto library
- `dnssec-aws-lc-rs`: DNSSEC with aws-lc-rs crypto library

## Comparison: agnostic vs agnostic-lite

| Feature | agnostic | agnostic-lite |
|---------|----------|---------------|
| Task spawning | ✅ | ✅ |
| Time operations | ✅ | ✅ |
| Networking | ✅ | ❌ |
| DNS resolution | ✅ | ❌ |
| Process management | ✅ | ❌ |
| QUIC support | ✅ | ❌ |
| `no_std` support | ❌ | ✅ |
| Alloc-free | ❌ | ✅ |
| No unsafe code | ❌ | ✅ |

Use `agnostic-lite` when:
- You need `no_std` or embedded support
- You want minimal dependencies
- You only need basic async primitives

Use `agnostic` when:
- You need networking, DNS, or process capabilities
- You're building standard applications
- You want a batteries-included experience

#### License

`agnostic` is under the terms of both the MIT license and the
Apache License (Version 2.0).

See [LICENSE-APACHE](LICENSE-APACHE), [LICENSE-MIT](LICENSE-MIT) for details.

Copyright (c) 2025 Al Liu.

[Github-url]: https://github.com/al8n/agnostic/
[CI-url]: https://github.com/al8n/agnostic/actions/workflows/ci.yml
[doc-url]: https://docs.rs/agnostic
[crates-url]: https://crates.io/crates/agnostic
[codecov-url]: https://app.codecov.io/gh/al8n/agnostic/

