pop-server - a puppet server, at your command.

This a web-server that helps you simulate behaviours and test integrations with external systems.

Overview

pop-server is a lightweight HTTP server that allows dynamic behavior registration and retrieval. It acts as a simple puppet server where you can define request-response behaviors dynamically via HTTP requests. This can be useful for testing, mocking APIs, or creating programmable server responses.

Features

• Register custom behaviors dynamically via HTTP headers and request bodies.
• Fetch stored behaviors based on incoming requests.
• Supports custom HTTP methods, paths, content types, and response statuses.
• Built with Rust, using Hyper for HTTP handling and Tokio for async networking.

Installation

You can find releases at:

• crates.io: https://crates.io/crates/pop-server
• dockerhub: https://hub.docker.com/repository/docker/jjba23/pop-server/general

A Nix flake is provided at the root of this repo.

If you don't use Nix, ensure you have Rust installed. You can install Rust via rustup: https://rustup.rs/

The project uses Cargo to build Rust code and Makefile for automating tasks and the build processes.

Usage

By default, the server listens on http://127.0.0.1:50088

It can be useful to use different logging levels, with the RUST_LOG environment variable, e.g. debug, info

You can start pop-server with certain environment variables to override behaviors:

POP_SERVER_LISTEN_PORT - HTTP port where pop-server listens, defaults to 50088

POP_SERVER_REGISTER_ROUTE - Route where behaviors are registered, defaults to /api/v2/pop-server/register-behavior

Register a Behavior

To register a new behavior (in memory), send a POST request to the register route, by default /api/v2/pop-server/register-behavior , with custom headers and a body:

curl -X POST "http://127.0.0.1:50088/api/v2/pop-server/register-behavior" \
   -H "content-type: application/json" \       
   -H "x-pop-server-request-method: GET" \
   -H "x-pop-server-request-path: /test" \
   -H "x-pop-server-response-content-type: application/json" \
   -H "x-pop-server-response-status: 200" \
   --data '{"message": "Hello, world!"}'

Fetch a Behavior

Once a behavior is registered (in-memory), you can retrieve it by making a request matching the registered method and path:

curl -X GET "http://127.0.0.1:50088/test"

If a match is found, the stored behavior is returned; otherwise, a 404 Not Found response is given.

API Reference

POST /api/v2/pop-server/register-behavior

Endpoint to register behaviors.

Headers:

• x-pop-server-request-method: HTTP method (e.g., GET, POST, etc.)
• x-pop-server-request-path: Path to match (e.g., /test)
• x-pop-server-response-content-type: Content-type of response
• x-pop-server-response-status: HTTP status code (default: 200)
• x-pop-server-request-content-type: Optional, Content-type of the incoming request, useful for e.g. POST

Body:

• JSON or any other valid body content that you wish to later return.

Dynamic Behavior Matching

If an incoming request matches a registered behavior (method & path), the server responds with the stored content.

Otherwise, it returns a 404 Not Found.

License

pop-server is licensed under the Lesser GNU General Public License v3.0. See the COPYING file or https://www.gnu.org/licenses/lgpl-3.0.html for more details.

Author

Created by Josep Bigorra (jjba23). For contributions, issues, or questions, contact: mailto:jjbigorra@gmail.com.