api.h

Go to the documentation of this file.

 
#pragma once
 
// The thread setting of this build, and the check that a translation unit agrees with it. Every public header
// that includes Asio reaches api.h.
#include <neograph/build_config.h>
 
#if defined(NEOGRAPH_STATIC_BUILD)
// Static-only build: no decoration, every symbol is a normal
// member of the static archive.
#define NEOGRAPH_API
#elif defined(_WIN32) || defined(__CYGWIN__)
#if defined(NEOGRAPH_BUILDING_LIBRARY)
#define NEOGRAPH_API __declspec(dllexport)
#else
#define NEOGRAPH_API __declspec(dllimport)
#endif
#elif defined(__GNUC__) && __GNUC__ >= 4
// Linux/macOS: explicit default visibility so a downstream
// library built with -fvisibility=hidden still sees these.
#define NEOGRAPH_API __attribute__((visibility("default")))
#else
#define NEOGRAPH_API
#endif
 
// Harness declarations belong to neograph_mcp_server but are also consumed by
// the MCP client, A2A adapter, and SQLite store libraries.
#if defined(NEOGRAPH_STATIC_BUILD)
#define NEOGRAPH_MCP_SERVER_API
#elif defined(_WIN32) || defined(__CYGWIN__)
#if defined(NEOGRAPH_BUILDING_MCP_SERVER)
#define NEOGRAPH_MCP_SERVER_API __declspec(dllexport)
#else
#define NEOGRAPH_MCP_SERVER_API __declspec(dllimport)
#endif
#elif defined(__GNUC__) && __GNUC__ >= 4
#define NEOGRAPH_MCP_SERVER_API __attribute__((visibility("default")))
#else
#define NEOGRAPH_MCP_SERVER_API
#endif
 
// Harness declarations are owned by the top-level neograph_harness adapter.
#if defined(NEOGRAPH_STATIC_BUILD)
#define NEOGRAPH_HARNESS_API
#elif defined(_WIN32) || defined(__CYGWIN__)
#if defined(NEOGRAPH_BUILDING_HARNESS)
#define NEOGRAPH_HARNESS_API __declspec(dllexport)
#else
#define NEOGRAPH_HARNESS_API __declspec(dllimport)
#endif
#elif defined(__GNUC__) && __GNUC__ >= 4
#define NEOGRAPH_HARNESS_API __attribute__((visibility("default")))
#else
#define NEOGRAPH_HARNESS_API
#endif
 
// Program value declarations are owned by neograph_program. A distinct macro
// prevents Windows consumers from importing them from neograph_core.
#if defined(NEOGRAPH_STATIC_BUILD)
#define NEOGRAPH_PROGRAM_API
#elif defined(_WIN32) || defined(__CYGWIN__)
#if defined(NEOGRAPH_BUILDING_PROGRAM)
#define NEOGRAPH_PROGRAM_API __declspec(dllexport)
#else
#define NEOGRAPH_PROGRAM_API __declspec(dllimport)
#endif
#elif defined(__GNUC__) && __GNUC__ >= 4
#define NEOGRAPH_PROGRAM_API __attribute__((visibility("default")))
#else
#define NEOGRAPH_PROGRAM_API
#endif
 
// PR 4 (v0.4.0): cross-compiler deprecation-warning suppression.
// Used inside the engine where the legacy 8-virtual default chain
// and add_cancel_hook fallback paths legitimately call deprecated
// symbols on behalf of consumers who haven't migrated yet. User
// code calling the same symbols still sees the warning.
//
//   GCC / clang  → -Wdeprecated-declarations
//   MSVC         → C4996
//
// Block-style usage:
//   NEOGRAPH_PUSH_IGNORE_DEPRECATED
//   // ... legacy default chain body ...
//   NEOGRAPH_POP_IGNORE_DEPRECATED
#if defined(__GNUC__) || defined(__clang__)
#define NEOGRAPH_PUSH_IGNORE_DEPRECATED \
    _Pragma("GCC diagnostic push") _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
#define NEOGRAPH_POP_IGNORE_DEPRECATED _Pragma("GCC diagnostic pop")
#elif defined(_MSC_VER)
#define NEOGRAPH_PUSH_IGNORE_DEPRECATED __pragma(warning(push)) __pragma(warning(disable : 4996))
#define NEOGRAPH_POP_IGNORE_DEPRECATED __pragma(warning(pop))
#else
#define NEOGRAPH_PUSH_IGNORE_DEPRECATED
#define NEOGRAPH_POP_IGNORE_DEPRECATED
#endif
 
// =========================================================================
// Issue #16 — silent ODR-trap detection for cpp-httplib + OpenSSL.
//
// NeoGraph's bundled cpp-httplib is built with `CPPHTTPLIB_OPENSSL_SUPPORT`
// defined (TLS ON). cpp-httplib's `ClientImpl` class adds extra members
// when this macro is set, so a downstream TU that includes `<httplib.h>`
// WITHOUT the macro sees a different class layout — a One Definition Rule
// violation. The linker keeps a single inline-function instantiation
// arbitrarily, so callers compiled against the wrong layout read members
// at the wrong offsets and SEGV inside the resolver
// (`getaddrinfo` / `internal_strlen`) the first time the LLM endpoint
// is hit.
//
// This guard catches the ordering case where the user's TU includes
// `<httplib.h>` BEFORE the first NeoGraph header (the natural order in
// many builds — system headers first, project headers second). The
// cpp-httplib include guard `CPPHTTPLIB_HTTPLIB_H` is already defined
// at this point, and we can compare macro state.
//
// Caveat: this guard does NOT fire when the user includes any NeoGraph
// header BEFORE `<httplib.h>` — at that point cpp-httplib hasn't been
// processed yet, its include guard isn't visible, so we have nothing to
// check against. For that ordering, the docstring on
// `include/neograph/llm/schema_provider.h` and
// `docs/troubleshooting.md` "C++ consumers — httplib.h macro
// consistency" explain the symptom and the fix.
//
// Disable the guard with `-DNEOGRAPH_SKIP_HTTPLIB_MACRO_GUARD=1` in
// build flags — last-resort escape for downstream TUs that have a
// genuine reason to mismatch (vanishingly rare; the canonical fix is
// to define the macro consistently).
#if defined(CPPHTTPLIB_HTTPLIB_H) && !defined(CPPHTTPLIB_OPENSSL_SUPPORT) && \
    !defined(NEOGRAPH_SKIP_HTTPLIB_MACRO_GUARD)
#error \
    "NeoGraph: <httplib.h> was included before this NeoGraph header without CPPHTTPLIB_OPENSSL_SUPPORT defined. NeoGraph's bundled cpp-httplib is built with TLS support ON; a mismatched macro state between TUs is an ODR violation that silently SEGVs inside getaddrinfo at runtime (issue #16). Fix: `#define CPPHTTPLIB_OPENSSL_SUPPORT` BEFORE `#include <httplib.h>` in this TU, OR add `target_compile_definitions(<your_target> PRIVATE CPPHTTPLIB_OPENSSL_SUPPORT)` to your CMakeLists. See docs/troubleshooting.md \"C++ consumers — httplib.h macro consistency\". Last-resort opt-out: `-DNEOGRAPH_SKIP_HTTPLIB_MACRO_GUARD=1`."
#endif