Destiny

Destiny is a standalone lightweight web server that makes use of the latest Swift features to push performance to the limit of the language, and designed to be easy to use while using the minimum amount of dependencies.

It provides a router (which is used via a Swift Macro) that accepts middleware, redirects, routes, and route groups for processing requests.

Features like TLS/SSL, Web Sockets and embedded support are coming soon.

We provide a blueprint library, DestinyBlueprint, that lays out the API of Destiny's inner workings to perform optimally, empowering the developer to determine the data structures and types used (if you don't use the default implementations from DestinyDefaults).

Table of Contents

• Roadmap
  • Completed
  • WIP
  • TODO
• Techniques
  • TODO
  • Limitations
• Getting Started
  • Routes
    • Wildcards
• Benchmarks
  • Static
  • Dynamic
  • Conclusion
• Contributing
• Support
  • Funding

Roadmap

Completed

• Custom hostname and port (Nov 8, 2024)
• Middleware and Routes (Nov 8, 2024)
• Register middleware/routes after starting server (Nov 8, 2024)
• Support multiple data representations (Nov 8, 2024)
• Routes with parameters (Nov 8, 2024)
• CORS (Dec 9, 2024 | static CORS needs a little more work)
• Configure settings via Command Line Arguments (Dec 11, 2024)
• Redirects (Dec 11, 2024 | dynamic redirects need a little more work)
• Hybrid Routes (Dec 24, 2024 | see ConditionalRouteResponderProtocol)
• Route Groups (Dec 27, 2024)
• Error Middleware (Dec 29, 2024 | see ErrorResponderProtocol)
• Case insensitive routes (Feb 19, 2025 | dynamic routes need a little more work)
• Routes with wildcards (Feb 19, 2025)
• Better handling of clients to unlock more throughput (Feb 23, 2025)
• Response streaming (Aug 2, 2025)
• Typed throws where applicable (Aug 3, 2025)
• Foundation-less (Aug 5, 2025)
• Swift 6 Language Mode (Aug 5, 2025)
• Cookies (Aug 9, 2025)

WIP

• Metric Middleware
• DocC Documentation
• Unit testing
• SIMD processing for better performance
• File Middleware
• Rate Limit Middleware
• Optimal Memory Layout for stored objects
• Route queries
• Embedded support

TODO

• DocC Tutorials
• Cache Middleware
• Request body streaming
• Data Validation (form, POST, etc)
• Authentication
• TLS/SSL
• Web Sockets
• Native load balancing & clustering
• Support custom middleware & routes in default #router
• Support third-party macro expansions in #router

Techniques

List of techniques Destiny uses to push performance to the limits of the Swift Language.

Structs by default

To avoid heap allocation and pointer indirection

Noncopyable types

To avoid retain/release and ARC traffic

@inlinable annotation

To make sure we inline hot-paths as much as possible

Actor avoidance

To encourage better state management and data structures

InlineArrays

To avoid heap allocations (especially in hot-paths)

Concurrency

To maximize multi-core performance and support non-blocking operations

Macros

Unlocks compile-time optimizations for middleware, routes, route groups and responders

Most compile-time optimizations for optimal runtime performance happens here. This includes:

• auto generation of optimized enums and structs for middleware, responders, route groups and route storage
• perfect hashing for static route storage (if possible)

Parameter Packs

For compile-time array optimizations, reducing heap allocations and dynamic dispatch

Opaque types

To avoid dynamic dispatch, existentials and boxing (especially in hot-paths)

Generic parameters

Only where opaque types aren't applicable to avoid dynamic dispatch, existentials and boxing (especially in hot-paths)

Typed throws

To improve runtime performance and a step closer to support embedded; eliminates heap allocation, metadata and dynamic dispatch for error handling

Swift 6 Language Mode

To avoid data races by enforcing compile time data race safety

Code Generation

For tedious work and easier development

Minimal Dependencies

To reduce binary size and simplify development

• no Foundation
• no SwiftNIO

Module Abstractions

To simplify and allow more control over development implementations

Benchmarks and performance profiling

To determine best data structures and techniques for optimal performance without sacrificing functionality

TODO

List of techniques Destiny wants to incorporate to push performance even further, not strictly Swift related.

• file descriptor pool
• connection pool
• optionally batch responses
• kqueue support

Limitations

Areas that Swift needs more development/support to unlock more performance at the language level.

• ~Copyable types in parameter packs (current Copyable requirement causes retain/release and ARC traffic)
• ~Copyable types not being able to be used as a typealias or associatedtype

Getting started

coming soon...

Routes

Wildcards

• * and :<param name> = parameter
• ** = catchall

Benchmarks

• Libraries tested
  • RandomHashTags/destiny v0.2.0 (this library)
  • hummingbird-project/hummingbird v2.11.1
  • vapor/vapor v4.114.1

Static

Initial testing of a basic HTML response shows that this library has the lowest server latency, highest throughput and most consistent timings when serving the same content.

Dynamic

Depends on how much dynamic content you add, but initial testing compared to a Static response performs about the same, but usually costs a few microseconds more (~10-50). I am actively researching and testing improvements.

Conclusion

This library is the clear leader in reliability, performance and efficiency. Static content offer the best performance, while dynamic content still tops the charts.

Contributing

Create a PR.

Support

You can create a discussion here on GitHub for support or join my Discord server at https://discord.com/invite/VyuFQUpcUz.

Funding

This project was developed to allow everyone to create better http servers. I develop and maintain many free open-source projects full-time for the benefit of everyone.

You can show your financial appreciation for this project and others by sponsoring us here on GitHub or other ways listed in the FUNDING.yml.