limestone

package module
v0.0.0-...-0b259bd Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 22, 2026 License: MIT Imports: 24 Imported by: 0

README

= Limestone
ifdef::env-github[]
Gavin Kondrath <78187175+gavink97@users.noreply.github.com>
v1.0, 2026-11-22
:homepage: https://gav.ink
endif::[]
:toc:
:icons: font

== Getting Started
=== Installation
requirements:

```
docker
docker-compose
```

Ensure you have any docker images you need pulled (or built) before starting Limestone. For example:
```
docker pull traefik/whoami
```

== Caddyfile

=== Limestone Options
You can check `Caddyfile.example` for quickstart boilerplate

==== Docker Network
```
docker_network {docker_network}
```

Defines the docker network the members of the pool will join.

==== Default Pool
```
default_pool {pool_name}
```

Defines the default pool limestone will route to. *This is required.*

==== Default Pool Config
```
default_pool_config {
	backend_port 80
	health_path /
	min 1
	max 4
	target_inflight 2
	scale_out_cooldown 3s
	scale_in_cooldown 15s
	drain_grace 5s
}
```

Defines the default pool configuration for all pools. Pools will inherit these attributes if not defined.

==== Rules
```
rules {
	/api/abc {pool_name}
	/api/xyz {pool_name}
}
```

When using multiple pools you can define routing rules. Limestone will route to a pool based on the defined prefix.

==== Pool {pool_name}
```
pool {pool_name} {
	image {docker_image_name}
	backend_port 80
	health_path /
	min 1
	max 4
	target_inflight 2
	scale_out_cooldown 3s
	scale_in_cooldown 15s
	drain_grace 5s
}
```

Defines a pool limestone will create and route to. *A `pool_name` and `image` are required to define a pool.*

=== Route Requirements
*Ensure limestone is defined in your `route` and limestone_pool in `reverse_proxy`*

```
:8080 {
	route {
		limestone
		reverse_proxy {
			dynamic limestone_pool
			lb_try_duration 5s
		}
	}
```

== Testing

=== Developer Endpoints
Important note: The Admin API is exposed at `0.0.0.0:2019` for injection testing purposes. In a production environment it is best advised to revert to `localhost:2019` or use `admin off`.

==== GET /limestone/pools
Returns a list of available pools.

==== GET /limestone/members/{pool_name}
Returns a list of pool members.

==== POST /limestone/test/reconciler/{pool_name}
This endpoint is designed to test the conditions that cause the reconciler to scale up, scale down, and retire members.

```
{
	"id": "member_id"
	"condition": "unhealthy | healthy | draining | remove | inflight"
	"inflight_demand": >= 0
}
```

=== Injection Testing
`testing/main.go` serves as a small yet expandable automated injection testing suite for assurance.

`--inflight` flag enables testing inflight injections which expand and decrease pool size.

`--verbose` flag enables verbose info logging of pool members and their state during the injection test.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AdminAPI

type AdminAPI struct {
	// contains filtered or unexported fields
}

func (AdminAPI) CaddyModule

func (AdminAPI) CaddyModule() caddy.ModuleInfo

func (*AdminAPI) Provision

func (a *AdminAPI) Provision(ctx caddy.Context) error

func (*AdminAPI) Routes

func (a *AdminAPI) Routes() []caddy.AdminRoute

type App

type App struct {
	DefaultPool            string                 `json:"default_pool,omitempty"`
	DockerNetwork          string                 `json:"docker_network,omitempty"`
	TickInterval           caddy.Duration         `json:"tick_interval,omitempty"`
	SpawnTimeout           caddy.Duration         `json:"spawn_timeout,omitempty"`
	KillOnStop             bool                   `json:"kill_on_stop,omitempty"`
	Pools                  []PoolConfig           `json:"pools,omitempty"`
	DefaultServiceProvider *ServiceProviderConfig `json:"default_service_provider,omitempty"`
	DefaultPoolConfig      *PoolConfig            `json:"default_pool_config,omitempty"`
	Rules                  []RouteRule            `json:"rules,omitempty"`
	// contains filtered or unexported fields
}

func (App) CaddyModule

func (App) CaddyModule() caddy.ModuleInfo

func (*App) Cleanup

func (a *App) Cleanup() error

func (*App) Provision

func (a *App) Provision(ctx caddy.Context) error

func (*App) Route

func (a *App) Route(r *http.Request) string

rules prints nil

func (*App) Start

func (a *App) Start() error

func (*App) Stop

func (a *App) Stop() error

func (*App) UnmarshalCaddyfile

func (a *App) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

type DockerProvisioner

type DockerProvisioner struct {
	// contains filtered or unexported fields
}

func (*DockerProvisioner) Adopt

func (p *DockerProvisioner) Adopt(ctx context.Context, knownPools map[string]*poolState) ([]Orphan, error)

func (*DockerProvisioner) Start

moby doesn't write a response on api calls, maybe a good first issue for moby

func (*DockerProvisioner) Stop

func (p *DockerProvisioner) Stop(ctx context.Context, id string) error

type Handler

type Handler struct {
	WaitCapacity time.Duration `json:"wait_capacity,omitempty"`
	// contains filtered or unexported fields
}

func (Handler) CaddyModule

func (Handler) CaddyModule() caddy.ModuleInfo

func (*Handler) Provision

func (h *Handler) Provision(ctx caddy.Context) error

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

func (*Handler) UnmarshalCaddyfile

func (h *Handler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

type Instance

type Instance struct {
	ID, Dial string
}

type MemberInfo

type MemberInfo struct {
	ID         string
	Dial       string
	Healthy    bool
	Draining   bool
	LastChange time.Time
}

type Orphan

type Orphan struct {
	Instance
	Pool string
}

type PoolConfig

type PoolConfig struct {
	Name             string                 `json:"name"`
	Image            string                 `json:"image"`
	BackendPort      int                    `json:"backend_port,omitempty"`
	HealthPath       string                 `json:"health_path,omitempty"`
	Min              int                    `json:"min,omitempty"`
	Max              int                    `json:"max,omitempty"`
	TargetInflight   int                    `json:"target_inflight,omitempty"`
	ScaleOutCooldown time.Duration          `json:"scale_out_cooldown,omitempty"`
	ScaleInCooldown  time.Duration          `json:"scale_in_cooldown,omitempty"`
	DrainGrace       time.Duration          `json:"drain_grace,omitempty"`
	ServiceProvider  *ServiceProviderConfig `json:"service_provider,omitempty"`
}

type PoolSource

type PoolSource struct {
	DefaultPool string `json:"default_pool,omitempty"`
	// contains filtered or unexported fields
}

func (PoolSource) CaddyModule

func (PoolSource) CaddyModule() caddy.ModuleInfo

func (*PoolSource) GetUpstreams

func (p *PoolSource) GetUpstreams(r *http.Request) ([]*reverseproxy.Upstream, error)

func (*PoolSource) Provision

func (p *PoolSource) Provision(ctx caddy.Context) error

func (*PoolSource) UnmarshalCaddyfile

func (ps *PoolSource) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

these are required otherwise caddy throws out an error: module http.reverse_proxy.upstreams.limestone_pool is not a Caddyfile unmarshaler

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

func NewRegistry

func NewRegistry(demand chan string) *Registry

func (*Registry) AddMember

func (r *Registry) AddMember(pool, id, dial string, healthy bool)

func (*Registry) Broadcast

func (r *Registry) Broadcast()

func (*Registry) HealthyCount

func (r *Registry) HealthyCount(pool string) int

func (*Registry) HealthyDials

func (r *Registry) HealthyDials(pool string) []string

func (*Registry) Inflight

func (r *Registry) Inflight(pool string) *atomic.Int64

Inflight returns the per-pool request counter. Waiting-for-capacity

func (*Registry) MarkDraining

func (r *Registry) MarkDraining(pool, id string)

func (*Registry) Members

func (r *Registry) Members(pool string) []MemberInfo

func (*Registry) Nudge

func (r *Registry) Nudge(pool string)

func (*Registry) RemoveMember

func (r *Registry) RemoveMember(pool, id string)

func (*Registry) SetHealth

func (r *Registry) SetHealth(pool, id string, healthy bool)

func (*Registry) WaitHealthy

func (r *Registry) WaitHealthy(ctx context.Context, pool string, max time.Duration) error

type RouteRule

type RouteRule struct {
	Prefix string
	Pool   string
}

type ServiceProviderConfig

type ServiceProviderConfig struct {
	Name   string `json:"name"`
	Region string `json:"region,omitempty"`
	Plan   string `json:"plan,omitempty"`

	Tag    string
	SSHKEY string
}

type ServiceProviderConfigParams

type ServiceProviderConfigParams struct {
	Name   string `json:"name"`
	Region string `json:"region,omitempty"`
	Plan   string `json:"plan,omitempty"`
	Tag    string
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL