aboutsummaryrefslogtreecommitdiff
path: root/tools/server
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-06-27 00:58:05 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-06-27 01:03:41 +0200
commitaf55803d0dff9eb692c760c8d486e736c945061d (patch)
tree0875a1112bf98304e445e0544c4309670d6f4769 /tools/server
parent0f861b7f3098750ddee4f6570f3be228d1da5320 (diff)
downloadffwd-af55803d0dff9eb692c760c8d486e736c945061d.tar.gz
ffwd-af55803d0dff9eb692c760c8d486e736c945061d.zip
chore: clean up comment formatting and wording
Diffstat (limited to 'tools/server')
-rw-r--r--tools/server/base64.h4
-rw-r--r--tools/server/encode.c30
-rw-r--r--tools/server/handlers.c45
-rw-r--r--tools/server/http.c24
-rw-r--r--tools/server/json.c24
-rw-r--r--tools/server/main.c15
-rw-r--r--tools/server/models.c29
-rw-r--r--tools/server/sbuf.h6
-rw-r--r--tools/server/schedule.c48
-rw-r--r--tools/server/server.h3
-rw-r--r--tools/server/server_internal.h14
-rw-r--r--tools/server/test_encode.c2
-rw-r--r--tools/server/test_util.h2
-rw-r--r--tools/server/util.h11
14 files changed, 140 insertions, 117 deletions
diff --git a/tools/server/base64.h b/tools/server/base64.h
index 2e77e2d..41277d1 100644
--- a/tools/server/base64.h
+++ b/tools/server/base64.h
@@ -5,8 +5,8 @@
/* Standard base64 (with '=' padding). */
-/* Number of base64 characters for n input bytes, excluding any NUL. Aborts
- * (die-on-OOM) if n is so large the length would overflow. */
+/* Number of base64 characters for n input bytes, excluding any NUL.
+ * Aborts (die-on-OOM) if n is so large the length would overflow. */
size_t base64_encoded_len(size_t n);
/* Encode n bytes of src as base64 into dst, writing exactly base64_encoded_len(n)
diff --git a/tools/server/encode.c b/tools/server/encode.c
index 63df965..9b6091f 100644
--- a/tools/server/encode.c
+++ b/tools/server/encode.c
@@ -1,3 +1,12 @@
+/* Embedding output encoding.
+ *
+ * Turns a pooled float vector into the requested wire form.
+ *
+ * - OpenAI-compatible models emit true float32 arrays by default.
+ * - Perplexity-compatible models emit tanh-quantized int8 by default,
+ * and their "float" view is the decoded int8 value for SDK compatibility.
+ */
+
#include "server_internal.h"
#include "util.h"
#include "sbuf.h"
@@ -8,15 +17,6 @@
#include <stdlib.h>
#include <string.h>
-/* ========================================================================
- * Embedding output encoding
- *
- * Turns a pooled float vector into the requested wire form. OpenAI-compatible
- * models emit true float32 arrays by default. Perplexity-compatible models
- * emit tanh-quantized int8 by default, and their "float" view is the decoded
- * int8 value for SDK compatibility.
- * ======================================================================== */
-
signed char quantize_int8_tanh(float x) {
int v = (int)lrintf(tanhf(x) * 127.0f);
if (v > 127)
@@ -26,9 +26,10 @@ signed char quantize_int8_tanh(float x) {
return (signed char)v;
}
-/* The bytes to base64 for `encoding`. "base64" aliases the float vector
- * (*owned = 0); "base64_int8" and "base64_binary" return a freshly allocated
- * buffer the caller frees (*owned = 1). */
+/* Bytes to base64-encode.
+ * "base64" aliases the float vector (*owned = 0).
+ * "base64_int8" and "base64_binary" return a new buffer for the caller to free
+ * (*owned = 1). */
static const unsigned char *
embedding_bytes(const float *emb, int dims, const char *encoding, size_t *n_out, int *owned) {
if (!strcmp(encoding, "base64")) {
@@ -71,9 +72,8 @@ static void sbuf_append_base64(sbuf *b, const unsigned char *src, size_t n) {
void append_embedding_value(
sbuf *b, int index, const float *emb, int dims, const char *encoding, embedding_api_t api) {
if (!strcmp(encoding, "float")) {
- /* Floats are hand-formatted with %.9g (the shortest form that
- * round-trips float32) and streamed into the sbuf, never serialized
- * through yyjson's writer. */
+ /* Floats are hand-formatted with %.9g (the shortest form that round-trips float32)
+ * and streamed into the sbuf, never serialized through yyjson's writer. */
sbuf_printf(b, "{\"object\":\"embedding\",\"index\":%d,\"embedding\":[", index);
for (int i = 0; i < dims; i++) {
if (i)
diff --git a/tools/server/handlers.c b/tools/server/handlers.c
index 2c98077..204f29e 100644
--- a/tools/server/handlers.c
+++ b/tools/server/handlers.c
@@ -1,3 +1,17 @@
+/* Endpoint handlers: prepare, batch, execute, render.
+ *
+ * Each endpoint has one prepare_* function that validates request JSON and
+ * tokenizes inputs into a *_request.
+ *
+ * The worker in schedule.c groups compatible ready requests and calls the
+ * matching execute_*_request_list.
+ *
+ * execute_*_request_list runs the batched forward pass through model_ffwd_* and
+ * renders each response through encode.c.
+ *
+ * Rerank scores late-interaction token vectors with MaxSim.
+ */
+
#include "server_internal.h"
#include "util.h"
#include "ffwd.h"
@@ -7,16 +21,6 @@
#include <stdlib.h>
#include <string.h>
-/* ========================================================================
- * Endpoint handlers: prepare, batch, execute, render
- *
- * One prepare_* per endpoint validates the request JSON and tokenizes its
- * inputs into a *_request; the worker (schedule.c) groups compatible
- * ready requests and calls the matching execute_*_request_list, which runs the
- * batched forward pass through model_ffwd_* and renders each response via
- * encode.c. Rerank runs MaxSim over late-interaction token vectors.
- * ======================================================================== */
-
int embedding_request_compatible(const embedding_request *a, const embedding_request *b) {
return a->ready && b->ready && a->model == b->model && a->dims == b->dims &&
!strcmp(a->encoding, b->encoding);
@@ -27,10 +31,11 @@ typedef struct {
int output_index;
} embedding_batch_item;
-/* Hand JSON serialization to the renderer thread only when another batch is
- * already queued, so the worker can start that GPU launch while these results
- * serialize. With nothing else queued the worker renders inline, which avoids a
- * thread hand-off that buys no overlap and adds latency to the reply. */
+/* Send JSON serialization to the renderer thread only when another batch is
+ * already queued, letting the worker start that GPU launch while these results
+ * serialize.
+ * If nothing else is queued, the worker renders inline to avoid a thread handoff
+ * that adds reply latency without buying overlap. */
static int render_should_defer(http_server *s) { return worker_has_pending_jobs(s); }
static int embedding_batch_item_cmp(const void *a, const void *b) {
@@ -513,9 +518,9 @@ void prepare_contextual_request(job *j,
for (int k = 0; k < n_chunks; k++) {
doc->spans[k].start = pos;
doc->spans[k].n_tokens = chunk_tokens[k].n_tokens;
- /* n_tokens > 0 implies ids != NULL (tokenize_one sets both
- * together), and the guard avoids a memcpy(dst, NULL, 0) for
- * an empty chunk that the static analyzer reports as UB. */
+ /* n_tokens > 0 means ids != NULL because tokenize_one sets both together.
+ * The guard also avoids memcpy(dst, NULL, 0) for empty chunks, which static
+ * analyzers report as UB. */
if (chunk_tokens[k].n_tokens > 0)
memcpy(doc->ids + pos, chunk_tokens[k].ids,
(size_t)chunk_tokens[k].n_tokens * sizeof(*doc->ids));
@@ -585,9 +590,9 @@ void prepare_rerank_request(job *j, yyjson_doc *root_doc, http_server *s, rerank
validate_rerank_model(root, detail, s, &out->model);
yyjson_val *query = yyjson_obj_get(root, "query");
yyjson_val *documents = yyjson_obj_get(root, "documents");
- /* query_str is set only once query passes every check; the tokenize step
- * below runs only when detail is empty, so it is non-NULL there. Hoisting it
- * also keeps the validated value explicit for the static analyzer. */
+ /* query_str is set only once query passes every check; the tokenize step below runs only
+ * when detail is empty, so it is non-NULL there.
+ * Hoisting it also keeps the validated value explicit for the static analyzer. */
const char *query_str = NULL;
if (!query) {
ve_add(detail, "[\"body\",\"query\"]", "field required", "missing");
diff --git a/tools/server/http.c b/tools/server/http.c
index a1d347f..6fc21f0 100644
--- a/tools/server/http.c
+++ b/tools/server/http.c
@@ -1,3 +1,16 @@
+/* HTTP/1.1 connection lifecycle, header parsing, and response framing.
+ *
+ * - One refcounted client per connection.
+ * - The event loop holds a reference while the socket is open; the worker thread
+ * holds one while a job from that connection is in flight.
+ * - If a request completes after the peer disconnects, the client is still freed
+ * safely.
+ * - read_cb accumulates bytes until a full request is framed, then hands it to
+ * dispatch_request in server.c.
+ * - write_cb drains the response, then either closes the connection or arms the
+ * next pipelined request.
+ */
+
#include "server_internal.h"
#include "util.h"
@@ -11,17 +24,6 @@
#include <sys/types.h>
#include <unistd.h>
-/* ========================================================================
- * HTTP/1.1 connection lifecycle, header parsing, and response framing
- *
- * One client per connection, refcounted: the event loop holds a reference
- * while the socket is open and the worker thread holds one while a job derived
- * from the connection is in flight, so a request that completes after the peer
- * disconnects frees the client safely. read_cb accumulates bytes until a full
- * request is framed, then hands off to dispatch_request (server.c); write_cb
- * drains the response and either closes or arms the next pipelined request.
- * ======================================================================== */
-
int set_nonblock(int fd) {
int flags = fcntl(fd, F_GETFL, 0);
if (flags < 0)
diff --git a/tools/server/json.c b/tools/server/json.c
index 8f9aec2..43200a8 100644
--- a/tools/server/json.c
+++ b/tools/server/json.c
@@ -1,3 +1,15 @@
+/* Request validation and error bodies.
+ *
+ * This code builds two JSON error shapes:
+ * - OpenAI-style {"error":{message,type}} for transport/auth failures, via
+ * append_json_error, json_error_body, and job_set_error.
+ * - Perplexity-style {"detail":[...]} 422 responses for field validation, built
+ * from ve_add entries.
+ *
+ * parse_* and *_from_root helpers read and validate the request object.
+ * append_json_string escapes a value for use in a response.
+ */
+
#include "server_internal.h"
#include "util.h"
@@ -6,16 +18,6 @@
#include <stdlib.h>
#include <string.h>
-/* ========================================================================
- * Request validation and error bodies
- *
- * Two JSON shapes are produced here: the OpenAI-style {"error":{message,type}}
- * body (append_json_error / json_error_body / job_set_error) for transport and
- * auth failures, and the Perplexity-style {"detail":[...]} 422 body built from
- * ve_add entries for field validation. The parse_* / *_from_root helpers read
- * and validate the request object; append_json_string escapes a value for
- * inclusion in a response. */
-
static void append_json_error(sbuf *b, const char *message, const char *type) {
sbuf_puts(b, "{\"error\":{\"message\":");
append_json_string(b, message ? message : "");
@@ -182,7 +184,7 @@ const char *encoding_from_root(yyjson_val *root, yyjson_mut_doc *detail, embeddi
return v;
}
-/* Parse the `text_type` hint. Returns 1 when the model's query instruction
+/* Parse the text_type hint. Returns 1 when the model's query instruction
* should be prepended, 0 otherwise (document / absent). Models without a
* published query instruction reject the field. */
int text_type_is_query(yyjson_val *root, yyjson_mut_doc *detail, const char *query_instruct) {
diff --git a/tools/server/main.c b/tools/server/main.c
index b94d438..baa4e39 100644
--- a/tools/server/main.c
+++ b/tools/server/main.c
@@ -1,10 +1,13 @@
-/* main.c - ffwd-server entry point.
+/* ffwd HTTP frontend.
*
- * The frontend for the ffwd-server binary: argument parsing, model-spec
- * handling, and main(). The server logic lives in server.c; this file only
- * builds the ffwd_server_config_t and calls ffwd_run_server. It is split
- * from server.c so the test suite can include server.c (for its internal
- * functions) without a conflicting main() and without a compile-out guard. */
+ * Handles argument parsing, model specs, and main().
+ * Server logic lives in server.c; this file only builds ffwd_server_config_t
+ * and calls ffwd_run_server.
+ *
+ * Split from server.c so tests can include server.c for internal functions
+ * without a conflicting main() or compile-out guard.
+ */
+
#include "build.h"
#include "server.h"
#include "server_internal.h"
diff --git a/tools/server/models.c b/tools/server/models.c
index 91aee18..2cb35a6 100644
--- a/tools/server/models.c
+++ b/tools/server/models.c
@@ -1,3 +1,16 @@
+/* Model load/lifecycle, plus tokenization and inference dispatch.
+ *
+ * Each loaded model owns resolved serving metadata for the operator-chosen
+ * label.
+ *
+ * Transformer behavior comes from model files through ffwd_config.
+ * Server-only facts missing from those files, such as output API family and
+ * Matryoshka floor, come from the load spec.
+ *
+ * tokenize_* and model_ffwd_* helpers are the request handlers' single dispatch
+ * point, hiding the compiled backend choice behind one signature.
+ */
+
#include "server_internal.h"
#include "util.h"
@@ -8,17 +21,6 @@
#include <string.h>
#include <unistd.h>
-/* ========================================================================
- * Model load/lifecycle, and tokenize/inference dispatch
- *
- * Each loaded model owns resolved serving metadata for the operator-chosen
- * label. Transformer behavior comes from the model files through ffwd_config;
- * server-only facts absent from those files, such as output API family and
- * Matryoshka floor, come from the load spec. The tokenize_* and model_ffwd_*
- * helpers are the single dispatch point the request handlers call, hiding the
- * compiled backend choice behind one signature.
- * ======================================================================== */
-
loaded_model *loaded_model_for_label(http_server *s, const char *label) {
if (!label)
return NULL;
@@ -195,9 +197,8 @@ void rerank_request_free(rerank_request *r) {
memset(r, 0, sizeof(*r));
}
-/* Tokenization itself lives in libffwd (ffwd_tok). These thin wrappers only
- * add the server's per-stage timing onto the job; the request handlers call
- * them unchanged. */
+/* Thin wrappers that add server per-stage timing to the tokenization job.
+ * Request handlers call them unchanged. */
int tokenize_input(
loaded_model *m, job *j, const char *text, const char *query_instruct, token_buf *out) {
uint64_t t0 = nstime();
diff --git a/tools/server/sbuf.h b/tools/server/sbuf.h
index 3116090..8053609 100644
--- a/tools/server/sbuf.h
+++ b/tools/server/sbuf.h
@@ -3,9 +3,9 @@
#include <stddef.h>
-/* Growable, always-NUL-terminated byte buffer used to build HTTP responses and
- * JSON bodies. Growth is die-on-OOM (see server_util.h), so the mutators never
- * fail; callers do not check return values. */
+/* Growable, always-NUL-terminated byte buffer for HTTP responses and JSON bodies.
+ * Growth is die-on-OOM; see server_util.h.
+ * Mutators never fail, so callers do not check return values. */
typedef struct {
char *ptr;
diff --git a/tools/server/schedule.c b/tools/server/schedule.c
index d57fbed..8254739 100644
--- a/tools/server/schedule.c
+++ b/tools/server/schedule.c
@@ -1,3 +1,21 @@
+/* Job queue, micro-batching, and completion.
+ *
+ * dispatch_request in server.c enqueues one job per framed request.
+ *
+ * The inference worker thread, worker_main in server.c, drains jobs with
+ * collect_job_batch. A short first-arrival wait groups concurrent arrivals.
+ *
+ * process_job_group routes each job to its endpoint handler and merges all
+ * compatible requests into one pool. execute_*_request_list then repacks that
+ * pool into token-budget batches.
+ *
+ * Finished jobs go to the done queue and wake the event loop through the
+ * completion pipe.
+ *
+ * completion_cb writes each response on the loop thread, so sockets are only
+ * touched there.
+ */
+
#include "server_internal.h"
#include "util.h"
@@ -9,19 +27,6 @@
#include <sys/time.h>
#include <unistd.h>
-/* ========================================================================
- * Job queue, micro-batching, and completion
- *
- * dispatch_request (server.c) enqueues one job per framed request; the
- * inference worker thread (worker_main, server.c) drains them with
- * collect_job_batch (a short first-arrival wait groups concurrent arrivals) and
- * runs process_job_group, which routes each job to its endpoint handler and
- * merges all compatible requests into one pool that execute_*_request_list
- * re-packs into token-budget batches. Finished jobs go on the done queue and
- * wake the event loop through the completion pipe; completion_cb writes each
- * response back on the loop thread, so sockets are only ever touched there.
- * ======================================================================== */
-
static void enqueue_done(job *j) {
http_server *s = j->srv;
pthread_mutex_lock(&s->mu);
@@ -324,12 +329,17 @@ static void process_unknown_job(job *j) {
yyjson_doc_free(root);
}
-/* Parse and tokenize one job into a heap request attached to j->prep, which the
- * worker then moves into its request array. Runs on the tokenizer thread, or on
- * the worker itself for a request that reached the job queue untokenized. An
- * unknown endpoint leaves prep_kind 0 (process_unknown_job handles it); a parse
- * failure leaves prep NULL with the 422 already set, so the worker finishes it
- * as not-ready. The tokenized flag guards against tokenizing twice. */
+/* Parse and tokenize one job into a heap request attached to j->prep.
+ * The worker later moves it into its request array.
+ *
+ * Runs on the tokenizer thread, or on the worker for requests that reached the
+ * job queue untokenized.
+ *
+ * Unknown endpoints leave prep_kind as 0; process_unknown_job handles them.
+ * Parse failures leave prep NULL with the 422 already set, so the worker
+ * finishes them as not-ready.
+ *
+ * tokenized prevents tokenizing twice. */
void tokenize_job(http_server *s, job *j) {
j->tokenized = 1;
if (!j->started_ns)
diff --git a/tools/server/server.h b/tools/server/server.h
index b8ec7e4..2add3f0 100644
--- a/tools/server/server.h
+++ b/tools/server/server.h
@@ -1,9 +1,6 @@
#ifndef FFWD_SERVER_H
#define FFWD_SERVER_H
-/* Public-API export annotation. The libraries are built with
- * -fvisibility=hidden, so only declarations carrying FFWD_API are exported
- * from the shared library; everything else stays internal. */
#ifndef FFWD_API
# if defined(__GNUC__)
# define FFWD_API __attribute__((visibility("default")))
diff --git a/tools/server/server_internal.h b/tools/server/server_internal.h
index 6f1f997..2369031 100644
--- a/tools/server/server_internal.h
+++ b/tools/server/server_internal.h
@@ -254,7 +254,7 @@ typedef struct {
int ready;
} rerank_request;
-/* ---- server_json.c: request validation and error bodies ---- */
+/* json.c: request validation and error bodies */
void append_json_string(sbuf *b, const char *s);
char *json_error_body(const char *message, const char *type, size_t *len);
void job_set_error(job *j, int status, const char *message, const char *type);
@@ -273,7 +273,7 @@ int text_type_is_query(yyjson_val *root, yyjson_mut_doc *detail, const char *que
int dimensions_from_root(
yyjson_val *root, yyjson_mut_doc *detail, int min_dim, int max_dim, const char *encoding);
-/* ---- server_http.c: connection lifecycle, header parse, response framing ---- */
+/* http.c: connection lifecycle, header parse, response framing */
int set_nonblock(int fd);
void client_incref(client *c);
void client_decref_n(client *c, int n);
@@ -293,7 +293,7 @@ void read_cb(aeEventLoop *loop, int fd, void *clientData, int mask);
/* Defined in server.c (request routing): framed requests are handed here. */
void dispatch_request(client *c);
-/* ---- server_encode.c: embedding output encoding ---- */
+/* encode.c: embedding output encoding */
signed char quantize_int8_tanh(float x);
void append_embedding_value(
sbuf *b, int index, const float *emb, int dims, const char *encoding, embedding_api_t api);
@@ -304,14 +304,14 @@ void job_render_free(job *j);
void job_set_embedding_render(job *j, const embedding_request *r, const float *embs);
int render_job_response(job *j);
-/* ---- server_models.c: model load/lifecycle, tokenize/inference dispatch ---- */
+/* models.c: model load/lifecycle, tokenize/inference dispatch */
loaded_model *loaded_model_for_label(http_server *s, const char *label);
void free_token_bufs(token_buf *t, int n);
void embedding_request_free(embedding_request *r);
void contextual_request_free(contextual_request *r);
void late_tokens_free(late_tokens *t);
void rerank_request_free(rerank_request *r);
-/* Thin timing wrappers over libffwd's ffwd_tokenize / ffwd_tokenize_late. */
+/* Thin timing wrappers over libffwd's ffwd_tokenize/ffwd_tokenize_late. */
int tokenize_one(loaded_model *m, job *j, const char *text, token_buf *out);
int tokenize_input(
loaded_model *m, job *j, const char *text, const char *query_instruct, token_buf *out);
@@ -328,7 +328,7 @@ int finalize_loaded_model(loaded_model *m);
int load_one_model(http_server *s, const ffwd_server_model_spec_t *spec);
void free_models(http_server *s);
-/* ---- server_handlers.c: per-endpoint prepare / batch-group / execute ---- */
+/* handlers.c: per-endpoint prepare/batch-group/execute */
void prepare_embedding_request(job *j, yyjson_doc *root_doc, http_server *s, embedding_request *out);
int embedding_request_compatible(const embedding_request *a, const embedding_request *b);
void execute_embedding_request_list(embedding_request **reqs, int n_reqs);
@@ -341,7 +341,7 @@ void execute_contextual_request_list(contextual_request **reqs, int n_reqs);
void prepare_rerank_request(job *j, yyjson_doc *root_doc, http_server *s, rerank_request *out);
void execute_rerank_request(rerank_request *r);
-/* ---- server_schedule.c: job queue, micro-batching, completion ---- */
+/* schedule.c: job queue, micro-batching, completion */
void enqueue_job(job *j);
int worker_has_pending_jobs(http_server *s);
void enqueue_raw_job(job *j);
diff --git a/tools/server/test_encode.c b/tools/server/test_encode.c
index f1959e4..eaadc9c 100644
--- a/tools/server/test_encode.c
+++ b/tools/server/test_encode.c
@@ -20,7 +20,7 @@ static void test_quantize_int8_tanh(void) {
TEST_ASSERT(quantize_int8_tanh(0.5f) == 59);
}
-/* Assert that rendering emb under `encoding` puts the base64 of `expect` in the
+/* Assert that rendering emb under encoding puts the base64 of expect in the
* embedding field of the response object. */
static void assert_base64_field(const float *emb,
int dims,
diff --git a/tools/server/test_util.h b/tools/server/test_util.h
index c6b6a13..551e0fb 100644
--- a/tools/server/test_util.h
+++ b/tools/server/test_util.h
@@ -4,7 +4,7 @@
/* Shared harness for the ffwd-server unit tests. TEST_ASSERT records failures
* (rather than aborting) so a single run reports every failure, not just the
* first. Each test file includes this, runs its checks, and ends main with
- * `return TEST_REPORT("label");`, which prints a summary and yields the exit
+ * return TEST_REPORT("label");, which prints a summary and yields the exit
* code (0 when clean, 1 otherwise). */
#include <stdio.h>
diff --git a/tools/server/util.h b/tools/server/util.h
index 3175cd0..97b1c48 100644
--- a/tools/server/util.h
+++ b/tools/server/util.h
@@ -5,10 +5,13 @@
#include <stddef.h>
/* Die-on-OOM allocation, monotonic clocks, and timestamped logging shared by
- * the ffwd-server translation units. The x* allocators abort the process on
- * failure rather than returning NULL, so callers never null-check them; the
- * attributes below carry that contract across translation-unit boundaries so
- * the static analyzer does not flag the (correctly) unchecked uses. */
+ * ffwd-server translation units.
+ *
+ * x* allocators abort on failure instead of returning NULL, so callers never
+ * null-check them.
+ *
+ * The attributes below carry that contract across translation-unit boundaries,
+ * preventing static-analyzer warnings for correctly unchecked uses. */
#if defined(__GNUC__) || defined(__clang__)
# define SERVER_NORETURN __attribute__((noreturn))