Pistache Documentation

Pistache is currently pre-1.0 and is considered unstable. While much of the code is production-ready for developing RESTful APIs, users should be aware of the following:

• HTTP Client: The HTTP client is currently buggy and may have issues.
• Platform Support: Pistache is primarily designed for Linux. It uses platform-specific APIs where the standard library lacks alternatives. Support for other platforms is not yet official.

To build the website and push it to the gh-pages branch for GitHub Pages hosting, use the yarn deploy command. You must provide your GitHub username via the GIT_USER environment variable. If you are using SSH for deployment, set USE_SSH=true.

GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy

Include the following snippet in your configure.ac to check for libpistache and set the appropriate CXXFLAGS and LIBS.

# Pistache...
PKG_CHECK_MODULES(
    [libpistache], [libpistache >= 0.0.2], [],
    [AC_MSG_ERROR([libpistache >= 0.0.2 missing...])])
YOURPROJECT_CXXFLAGS="$YOURPROJECT_CXXFLAGS $libpistache_CFLAGS"
YOURPROJECT_LIBS="$YOURPROJECT_LIBS $libpistache_LIBS"

Clone the repository and use Meson to configure, compile, and install the project. You can enable features like SSL and various content encodings via Meson options.

$ git clone https://github.com/pistacheio/pistache.git
$ cd pistache
$ meson setup build                                 \
    --buildtype=release                             \
    -DPISTACHE_USE_SSL=true                         \
    -DPISTACHE_BUILD_EXAMPLES=true                  \
    -DPISTACHE_BUILD_TESTS=true                     \
    -DPISTACHE_BUILD_DOCS=false                     \
    -DPISTACHE_USE_CONTENT_ENCODING_BROTLI=true     \
    -DPISTACHE_USE_CONTENT_ENCODING_DEFLATE=true    \
    -DPISTACHE_USE_CONTENT_ENCODING_ZSTD=true       \
    --prefix="$PWD/prefix"
$ meson compile -C build
$ meson install -C build

After defining your routes in an Http::Router instance, you must attach the router's handler to your Http::Endpoint using the handler() method.

endpoint.setHandler(router.handler());

For content where the length is unknown in advance, use chunked encoding via the ResponseStream class.

Important: Headers must be configured on the ResponseWriter before calling .stream(), as headers become immutable once the stream starts.

To use streaming:

1. Configure headers on the response object.
2. Call response.stream(Http::Code) to obtain a ResponseStream.
3. Use the << operator to write chunks.
4. Use the flush marker to push data without ending the stream.
5. Use the ends marker to finalize the stream and send the final data.

Use the FindPkgConfig module to locate libpistache and link against the imported target.

cmake_minimum_required(VERSION 3.6)
project("MyPistacheProject")

find_package(PkgConfig)
pkg_check_modules(Pistache REQUIRED IMPORTED_TARGET libpistache)

add_executable(${PROJECT_NAME} main.cpp)
target_link_libraries(${PROJECT_NAME} PkgConfig::Pistache)

Run the unit tests using Meson. You can skip tests that require network access using the --no-suite=network flag.

$ meson test -C build

To use daily unstable snapshots of Pistache, add the unstable PPA and install libpistache-dev.

$ sudo add-apt-repository ppa:pistache+team/unstable
$ sudo apt update
$ sudo apt install libpistache-dev

To install stable release packages, add the stable PPA and install libpistache-dev.

$ sudo add-apt-repository ppa:pistache+team/stable
$ sudo apt update
$ sudo apt install libpistache-dev