https://github.com/oxidecomputer/qorb

https://github.com/oxidecomputer/qorb

Last synced: 11 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/oxidecomputer/qorb
• Owner: oxidecomputer
• License: mpl-2.0
• Created: 2024-05-02T06:32:31.000Z (about 2 years ago)
• Default Branch: master
• Last Pushed: 2025-06-24T16:52:56.000Z (about 1 year ago)
• Last Synced: 2025-06-24T17:49:27.398Z (about 1 year ago)
• Language: Rust
• Size: 558 KB
• Stars: 9
• Watchers: 18
• Forks: 1
• Open Issues: 4
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Awesome Lists containing this project

README

          
:showtitle:

:toc: left

:icons: font

= Qorb

Qorb is a work-in-progress Connection Pooling library, heavily inspired by

the "Cueball" connection pooling library.

== Overview

Qorb's main interface is the link:https://docs.rs/qorb/latest/qorb/pool/struct.Pool.html[Pool] object.

This pool relies on two interfaces that can be customized:

* The link:https://docs.rs/qorb/latest/qorb/resolver/trait.Resolver.html[Resolver] interface identifies

how to locate backend servers. link:https://docs.rs/qorb/latest/qorb/resolvers/dns/struct.DnsResolver.html[DnsResolver]

provides a default implementation which queries DNS entries to access the set of backends.

* The link:https://docs.rs/qorb/latest/qorb/backend/trait.Connector.html[Connector] interface identifies

how to connect to a single backend. Within this method, the `connect` method is essential, but the `is_valid`

and `on_recycle` methods can optionally be implemented to perform (respectively) health checks and perform cleanup actions

before used connections are returned to the pool.

== Examples

To get up and running with a client, server, and DNS system, link:examples/README.adoc[refer to the README in the examples directory].

In particular, the link:examples/tcp_echo_workload/main.rs[TCP echo workload] example demonstrates

how to create a connection pool with a custom TCP connection.

This provides a setup for generating a workload to an arbitrary number of

backends, and then walks through the tools to inspect the connection pool.

== Terminology

* **Service**: A named entity which refers to a program that is running with one or more instantiations

as distinct backends.

* **Backend**: An specific instance of a program running a service. Each backend should provide the same interface, such that a client can access any one of the backends implementing a service interchangeably.

* **Resolver**: A client-side entity responsible for translating service name into backend location. A common

example of a resolver is "DNS".

* **Slot**: An allocated commitment to create a connection to a particular backend. A slot may be "connected"

if the connection has been established, or "connecting" if the backend hasn't yet been reached.

* **Slot Set**: A group of slots all attempting to access a particular backend. The number of slots

which are allocated for each backend is controlled by qorb, but may be adjusted via user-configurable policy.

* **Pool**: The a group of connections to one or more backends, from which a client of qorb can

"claim" a connection. The pool manages resolvers, finds backends, creates slots for backends, and vends

out connected slots to clients.

== TODO List

Things I'd like to do before getting more eyes on this:

* Add dtrace probes

* Add a baseline test suite