ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
main.cpp
Go to the documentation of this file.
1
14
15#include "http_server.h"
16#include "json.h"
17#include "lldb_controller.h"
18#include <libplatform/process.h>
20
21#include <csignal>
22#include <cstdio>
23#include <cstdlib>
24#include <cstring>
25#include <string>
26#include <climits>
27#include <vector>
28
29namespace {
30
31// Global controller and server (for signal handling)
32ascii_query::LLDBController *g_controller = nullptr;
33ascii_query::HttpServer *g_server = nullptr;
34volatile sig_atomic_t g_shutdown_requested = 0;
35
36struct ProcessEntry {
37 pid_t pid;
38 std::string name;
39};
40
41int collectAsciiChatProcess(const platform_process_info_t *process, void *context) {
42 auto *result = static_cast<std::vector<ProcessEntry> *>(context);
43 result->push_back({process->pid, process->name});
44 return 0;
45}
46
47std::vector<ProcessEntry> listAsciiChatProcesses() {
48 std::vector<ProcessEntry> result;
49 if (platform_process_list("ascii-chat", collectAsciiChatProcess, &result) != 0)
50 return {};
51 return result;
52}
53
54void signalHandler(int sig) {
55 (void)sig;
56 g_shutdown_requested = 1;
57 if (g_server) {
58 g_server->stop();
59 }
60}
61
62void printUsage(const char *program) {
63 fprintf(stderr, "Usage: %s [options]\n\n", program);
64 fprintf(stderr, "Options:\n");
65 fprintf(stderr, " --attach <pid> Attach to process by PID\n");
66 fprintf(stderr, " --attach-name <name> Attach to process by name\n");
67 fprintf(stderr, " --attach-ascii-chat Attach to the first running ascii-chat process\n");
68 fprintf(stderr, " --list-processes List running processes with ascii-chat in the name\n");
69 fprintf(stderr, " --wait Wait for process to start (with --attach-name)\n");
70 fprintf(stderr, " --port <port> HTTP server port (default: 9999)\n");
71 fprintf(stderr, " --help Show this help\n");
72 fprintf(stderr, "\nExamples:\n");
73 fprintf(stderr, " %s --attach 12345 --port 9999\n", program);
74 fprintf(stderr, " %s --attach-name ascii-chat --wait\n", program);
75 fprintf(stderr, "\nQuery endpoints:\n");
76 fprintf(stderr, " GET / Status page\n");
77 fprintf(stderr, " GET /process Process information\n");
78 fprintf(stderr, " GET /threads Thread list\n");
79 fprintf(stderr, " GET /frames Stack frames (when stopped)\n");
80 fprintf(stderr, " GET /query Query a variable\n");
81 fprintf(stderr, " POST /continue Resume execution\n");
82 fprintf(stderr, " POST /step Single step\n");
83 fprintf(stderr, " POST /detach Detach from process\n");
84}
85
86// Convert ProcessState to string
87const char *processStateToString(ascii_query::ProcessState state) {
88 switch (state) {
90 return "invalid";
92 return "running";
94 return "stopped";
96 return "exited";
98 return "crashed";
100 return "detached";
101 }
102 return "unknown";
103}
104
105// Build JSON for ThreadInfo
106ascii_query::json::JsonObject threadToJson(const ascii_query::ThreadInfo &thread) {
108 obj.set("id", thread.id);
109 obj.set("index", static_cast<int64_t>(thread.index));
110 obj.set("name", thread.name);
111 obj.set("stop_reason", thread.stop_reason);
112 obj.set("function", thread.function);
113 obj.set("file", thread.file);
114 obj.set("line", static_cast<int64_t>(thread.line));
115 obj.set("selected", thread.is_selected);
116 return obj;
117}
118
119// Build JSON for FrameInfo
122 obj.set("index", static_cast<int64_t>(frame.index));
123 obj.set("function", frame.function);
124 obj.set("file", frame.file);
125 obj.set("line", static_cast<int64_t>(frame.line));
126 obj.set("pc", frame.pc);
127 obj.set("fp", frame.fp);
128 return obj;
129}
130
131// Build JSON for VariableInfo
132ascii_query::json::JsonObject variableToJson(const ascii_query::VariableInfo &var, int max_depth = 3) {
134 obj.set("name", var.name);
135 obj.set("type", var.type);
136 obj.set("value", var.value);
137 if (!var.summary.empty()) {
138 obj.set("summary", var.summary);
139 }
140 obj.set("address", var.address);
141 obj.set("size", static_cast<int64_t>(var.size));
142 obj.set("valid", var.is_valid);
143 obj.set("pointer", var.is_pointer);
144 obj.set("aggregate", var.is_aggregate);
145
146 if (!var.children.empty() && max_depth > 0) {
148 for (const auto &child : var.children) {
149 children.add(variableToJson(child, max_depth - 1));
150 }
151 obj.set("children", children);
152 }
153
154 return obj;
155}
156
157// Build JSON for BreakpointInfo
160 obj.set("id", static_cast<int64_t>(bp.id));
161 obj.set("file", bp.file);
162 obj.set("line", static_cast<int64_t>(bp.line));
163 obj.set("condition", bp.condition);
164 obj.set("hit_count", static_cast<int64_t>(bp.hit_count));
165 obj.set("enabled", bp.enabled);
166 obj.set("resolved", bp.resolved);
167 return obj;
168}
169
170// Setup HTTP routes
171void setupRoutes(ascii_query::HttpServer &server, ascii_query::LLDBController &controller) {
172 using namespace ascii_query;
173 using namespace ascii_query::json;
174
175 // GET / - Status page (plain text for terminal users)
176 server.addRoute("GET", "/", [&controller](const HttpRequest &) {
177 ProcessState state = controller.state();
178 std::string state_str = processStateToString(state);
179
180 std::string text = "ascii-query-server\n";
181 text += "==================\n\n";
182 text += "Target PID: " + std::to_string(controller.targetPid()) + "\n";
183 text += "Target Name: " + controller.targetName() + "\n";
184 text += "State: " + state_str + "\n";
185 text += "\n";
186 text += "Endpoints:\n";
187 text += " GET / Status page (this)\n";
188 text += " GET /process Process information (JSON)\n";
189 text += " GET /threads Thread list (JSON)\n";
190 text += " GET /frames Stack frames when stopped (JSON)\n";
191 text += " GET /query?name=VAR Query a variable (JSON)\n";
192 text += " GET /breakpoints List breakpoints (JSON)\n";
193 text += " POST /continue Resume execution\n";
194 text += " POST /stop Stop execution\n";
195 text += " POST /step Single step (add ?over or ?out)\n";
196 text += " POST /detach Detach from process\n";
197 text += "\n";
198 text += "Examples:\n";
199 text += " curl localhost:9999/process\n";
200 text += " curl localhost:9999/query?name=frame.width\n";
201 text += " curl 'localhost:9999/query?file=server.c&line=100&name=client_count&break'\n";
202 text += " curl -X POST localhost:9999/continue\n";
203
204 return HttpResponse::text(text);
205 });
206
207 // GET /process - Process information
208 server.addRoute("GET", "/process", [&controller](const HttpRequest &) {
209 JsonObject obj;
210 obj.set("pid", static_cast<int64_t>(controller.targetPid()));
211 obj.set("name", controller.targetName());
212 obj.set("state", processStateToString(controller.state()));
213 obj.set("attached", controller.isAttached());
214 if (!controller.lastError().empty()) {
215 obj.set("last_error", controller.lastError());
216 }
217 return HttpResponse::json(obj.toString());
218 });
219
220 // GET /threads - Thread list
221 server.addRoute("GET", "/threads", [&controller](const HttpRequest &) {
222 auto threads = controller.getThreads();
223 JsonArray arr;
224 for (const auto &thread : threads) {
225 arr.add(threadToJson(thread));
226 }
227 JsonObject obj;
228 obj.set("count", static_cast<int64_t>(threads.size()));
229 obj.set("threads", arr);
230 return HttpResponse::json(obj.toString());
231 });
232
233 // GET /frames - Stack frames
234 server.addRoute("GET", "/frames", [&controller](const HttpRequest &req) {
235 int max_frames = req.paramInt("max", 50);
236 auto frames = controller.getFrames(static_cast<uint32_t>(max_frames));
237 JsonArray arr;
238 for (const auto &frame : frames) {
239 arr.add(frameToJson(frame));
240 }
241 JsonObject obj;
242 obj.set("count", static_cast<int64_t>(frames.size()));
243 obj.set("frames", arr);
244 return HttpResponse::json(obj.toString());
245 });
246
247 // GET /query - Query a variable
248 server.addRoute("GET", "/query", [&controller](const HttpRequest &req) {
249 std::string file = req.param("file");
250 int line = req.paramInt("line", 0);
251 std::string name = req.param("name");
252 int frame_index = req.paramInt("frame", 0);
253 int expand_depth = req.paramInt("depth", 0);
254 bool should_break = req.hasParam("break");
255 int timeout_ms = req.paramInt("timeout", 5000);
256
257 if (name.empty()) {
258 return HttpResponse::badRequest("Missing 'name' parameter");
259 }
260
261 ProcessState state = controller.state();
262 bool is_stopped = (state == ProcessState::Stopped);
263
264 // If we have file:line and need to break, set breakpoint
265 if (!file.empty() && line > 0 && should_break && !is_stopped) {
266 int bp_id = controller.setBreakpoint(file, static_cast<uint32_t>(line));
267 if (bp_id < 0) {
268 JsonObject obj;
269 obj.set("status", "error");
270 obj.set("error", "breakpoint_failed");
271 obj.set("message", "Failed to set breakpoint at " + file + ":" + std::to_string(line));
272 return HttpResponse::json(obj.toString());
273 }
274
275 bool hit = controller.waitForBreakpoint(static_cast<uint32_t>(timeout_ms));
276 if (!hit) {
277 controller.removeBreakpoint(bp_id);
278 JsonObject obj;
279 obj.set("status", "error");
280 obj.set("error", "timeout");
281 obj.set("message", "Breakpoint not hit within " + std::to_string(timeout_ms) + "ms");
282 return HttpResponse::json(obj.toString());
283 }
284 is_stopped = true;
285 }
286
287 // Read the variable
288 int actual_expand = expand_depth > 0 ? expand_depth : (req.hasParam("expand") ? 3 : 0);
289 auto var = controller.readVariable(name, static_cast<uint32_t>(frame_index), static_cast<uint32_t>(actual_expand));
290
291 if (!var) {
292 JsonObject obj;
293 obj.set("status", "error");
294 obj.set("error", "not_found");
295 obj.set("message", "Variable '" + name + "' not found");
296 obj.set("stopped", is_stopped);
297 return HttpResponse::json(obj.toString());
298 }
299
300 JsonObject obj;
301 obj.set("status", "ok");
302 obj.set("stopped", is_stopped);
303 obj.set("result", variableToJson(*var, actual_expand > 0 ? actual_expand : 3));
304 return HttpResponse::json(obj.toString());
305 });
306
307 // GET /breakpoints - List breakpoints
308 server.addRoute("GET", "/breakpoints", [&controller](const HttpRequest &) {
309 auto breakpoints = controller.getBreakpoints();
310 JsonArray arr;
311 for (const auto &bp : breakpoints) {
312 arr.add(breakpointToJson(bp));
313 }
314 JsonObject obj;
315 obj.set("count", static_cast<int64_t>(breakpoints.size()));
316 obj.set("breakpoints", arr);
317 return HttpResponse::json(obj.toString());
318 });
319
320 // POST /breakpoints - Set breakpoint
321 server.addRoute("POST", "/breakpoints", [&controller](const HttpRequest &req) {
322 std::string file = req.param("file");
323 int line = req.paramInt("line", 0);
324 std::string condition = req.param("condition");
325
326 if (file.empty() || line <= 0) {
327 return HttpResponse::badRequest("Missing 'file' and 'line' parameters");
328 }
329
330 int bp_id = controller.setBreakpoint(file, static_cast<uint32_t>(line), condition);
331 if (bp_id < 0) {
332 JsonObject obj;
333 obj.set("status", "error");
334 obj.set("message", controller.lastError());
335 return HttpResponse::json(obj.toString());
336 }
337
338 auto bp = controller.getBreakpoint(bp_id);
339 JsonObject obj;
340 obj.set("status", "ok");
341 if (bp) {
342 obj.set("breakpoint", breakpointToJson(*bp));
343 }
344 return HttpResponse::json(obj.toString());
345 });
346
347 // DELETE /breakpoints - Remove breakpoint
348 server.addRoute("DELETE", "/breakpoints", [&controller](const HttpRequest &req) {
349 int bp_id = req.paramInt("id", -1);
350 if (bp_id < 0) {
351 return HttpResponse::badRequest("Missing 'id' parameter");
352 }
353 bool removed = controller.removeBreakpoint(static_cast<int32_t>(bp_id));
354 JsonObject obj;
355 obj.set("status", removed ? "ok" : "error");
356 if (!removed) {
357 obj.set("message", "Breakpoint not found");
358 }
359 return HttpResponse::json(obj.toString());
360 });
361
362 // POST /continue - Resume execution
363 server.addRoute("POST", "/continue", [&controller](const HttpRequest &) {
364 bool resumed = controller.resume();
365 JsonObject obj;
366 obj.set("status", resumed ? "running" : "error");
367 if (!resumed) {
368 obj.set("error", controller.lastError());
369 }
370 return HttpResponse::json(obj.toString());
371 });
372
373 // POST /stop - Stop execution
374 server.addRoute("POST", "/stop", [&controller](const HttpRequest &) {
375 bool stopped = controller.stop();
376 JsonObject obj;
377 obj.set("status", stopped ? "stopped" : "error");
378 if (!stopped) {
379 obj.set("error", controller.lastError());
380 }
381 return HttpResponse::json(obj.toString());
382 });
383
384 // POST /step - Single step
385 server.addRoute("POST", "/step", [&controller](const HttpRequest &req) {
386 bool over = req.hasParam("over");
387 bool out = req.hasParam("out");
388 bool success = out ? controller.stepOut() : (over ? controller.stepOver() : controller.stepInto());
389 JsonObject obj;
390 obj.set("status", success ? "ok" : "error");
391 if (!success) {
392 obj.set("error", controller.lastError());
393 }
394 return HttpResponse::json(obj.toString());
395 });
396
397 // POST /detach - Detach from process
398 server.addRoute("POST", "/detach", [&controller](const HttpRequest &) {
399 controller.detach();
400 JsonObject obj;
401 obj.set("status", "detached");
402 return HttpResponse::json(obj.toString());
403 });
404}
405
406} // namespace
407
408int main(int argc, char *argv[]) {
409 // Parse command line arguments
410 pid_t attach_pid = 0;
411 std::string attach_name;
412 bool wait_for = false;
413 bool attach_ascii_chat = false;
414 bool list_processes = false;
415 uint16_t port = 9999;
416
417 for (int i = 1; i < argc; i++) {
418 if (strcmp(argv[i], "--help") == 0 || strcmp(argv[i], "-h") == 0) {
419 printUsage(argv[0]);
420 return 0;
421 } else if (strcmp(argv[i], "--attach") == 0 && i + 1 < argc) {
422 // Parse PID using safe parsing utility
423 unsigned long pid_val = 0;
424 if (parse_ulong(argv[++i], &pid_val, 1, ULONG_MAX) != ASCIICHAT_OK) {
425 fprintf(stderr, "Error: Invalid PID value\n");
426 return 1;
427 }
428 attach_pid = static_cast<pid_t>(pid_val);
429 } else if (strcmp(argv[i], "--attach-name") == 0 && i + 1 < argc) {
430 attach_name = argv[++i];
431 } else if (strcmp(argv[i], "--attach-ascii-chat") == 0) {
432 attach_ascii_chat = true;
433 } else if (strcmp(argv[i], "--list-processes") == 0 || strcmp(argv[i], "--list") == 0) {
434 list_processes = true;
435 } else if (strcmp(argv[i], "--wait") == 0) {
436 wait_for = true;
437 } else if (strcmp(argv[i], "--port") == 0 && i + 1 < argc) {
438 // Parse port using safe parsing utility with proper range validation
439 if (parse_port(argv[++i], &port) != ASCIICHAT_OK) {
440 fprintf(stderr, "Error: Invalid port number (must be 1-65535)\n");
441 return 1;
442 }
443 } else {
444 fprintf(stderr, "Unknown option: %s\n", argv[i]);
445 printUsage(argv[0]);
446 return 1;
447 }
448 }
449
450 if (list_processes) {
451 for (const auto &process : listAsciiChatProcesses()) {
452 fprintf(stdout, "%llu\t%s\n", static_cast<unsigned long long>(process.pid), process.name.c_str());
453 }
454 return 0;
455 }
456
457 if (attach_ascii_chat) {
458 const auto processes = listAsciiChatProcesses();
459 if (processes.empty()) {
460 fprintf(stderr, "Error: No running process with 'ascii-chat' in its name\n");
461 return 1;
462 }
463 attach_pid = processes.front().pid;
464 }
465
466 // Validate arguments
467 if (attach_pid == 0 && attach_name.empty()) {
468 fprintf(stderr, "Error: Must specify --attach <pid> or --attach-name <name>\n\n");
469 printUsage(argv[0]);
470 return 1;
471 }
472
473 // Setup signal handlers
474 signal(SIGINT, signalHandler);
475 signal(SIGTERM, signalHandler);
476#ifndef _WIN32
477 signal(SIGPIPE, SIG_IGN);
478#endif
479
480 // Initialize LLDB controller
482 g_controller = &controller;
483
484 if (!controller.initialize()) {
485 fprintf(stderr, "Error: Failed to initialize LLDB: %s\n", controller.lastError().c_str());
486 return 1;
487 }
488
489 // Attach to target
490 fprintf(stderr, "[ascii-query-server] Attaching to ");
491 if (attach_pid > 0) {
492 fprintf(stderr, "PID %llu...\n", static_cast<unsigned long long>(attach_pid));
493 if (!controller.attach(attach_pid)) {
494 fprintf(stderr, "Error: Failed to attach: %s\n", controller.lastError().c_str());
495 return 1;
496 }
497 } else {
498 fprintf(stderr, "process '%s'%s...\n", attach_name.c_str(), wait_for ? " (waiting)" : "");
499 if (!controller.attachByName(attach_name, wait_for)) {
500 fprintf(stderr, "Error: Failed to attach: %s\n", controller.lastError().c_str());
501 return 1;
502 }
503 }
504
505 fprintf(stderr, "[ascii-query-server] Attached to %s (PID %llu)\n", controller.targetName().c_str(), static_cast<unsigned long long>(controller.targetPid()));
506
507 // Resume the target (it's stopped after attach)
508 if (controller.state() == ascii_query::ProcessState::Stopped) {
509 fprintf(stderr, "[ascii-query-server] Resuming target...\n");
510 controller.resume();
511 }
512
513 // Setup HTTP server
515 g_server = &server;
516
517 setupRoutes(server, controller);
518
519 // Start HTTP server
520 if (!server.start(port)) {
521 fprintf(stderr, "Error: Failed to start HTTP server: %s\n", server.lastError().c_str());
522 controller.detach();
523 return 1;
524 }
525
526 fprintf(stderr, "[ascii-query-server] HTTP server listening on http://localhost:%d\n", port);
527 fprintf(stderr, "[ascii-query-server] Press Ctrl+C to stop\n");
528
529 // Wait for shutdown
530 while (!g_shutdown_requested && controller.isAttached()) {
531#ifdef _WIN32
532 Sleep(100);
533#else
534 usleep(100000);
535#endif
536 ascii_query::ProcessState state = controller.state();
538 fprintf(stderr, "[ascii-query-server] Target %s, shutting down\n", state == ascii_query::ProcessState::Exited ? "exited" : "crashed");
539 break;
540 }
541 }
542
543 // Cleanup
544 fprintf(stderr, "[ascii-query-server] Shutting down...\n");
545 server.stop();
546 controller.detach();
547 controller.shutdown();
548
549 fprintf(stderr, "[ascii-query-server] Done\n");
550 return 0;
551}
Simple single-threaded HTTP server.
void addRoute(const std::string &method, const std::string &path, RouteHandler handler)
Add a route handler.
bool start(uint16_t port)
Start the server.
const std::string & lastError() const
Get the last error message.
void stop()
Stop the server.
LLDB process controller.
int32_t setBreakpoint(const std::string &file, uint32_t line, const std::string &condition="")
Set a breakpoint at file:line.
bool attachByName(const std::string &process_name, bool wait_for=false)
Attach to a process by name.
bool removeBreakpoint(int32_t breakpoint_id)
Remove a breakpoint.
bool stepInto()
Single step the current thread (step into).
pid_t targetPid() const
Get the PID of the attached process.
std::string targetName() const
Get the name of the attached process.
std::optional< VariableInfo > readVariable(const std::string &name, uint32_t frame_index=0, uint32_t expand_depth=0) const
Read a variable from the current frame.
const std::string & lastError() const
Get the last error message.
bool initialize()
Initialize LLDB. Must be called before any other methods.
void shutdown()
Shutdown LLDB and release resources.
bool stop()
Stop the target process.
bool isAttached() const
Check if attached to a process.
std::vector< ThreadInfo > getThreads() const
Get list of all threads.
std::vector< BreakpointInfo > getBreakpoints() const
Get all breakpoints.
bool resume()
Resume the target process.
std::vector< FrameInfo > getFrames(uint32_t max_frames=0) const
Get stack frames for the selected thread.
bool stepOver()
Step over the current line.
std::optional< BreakpointInfo > getBreakpoint(int32_t breakpoint_id) const
Get information about a specific breakpoint.
bool stepOut()
Step out of the current function.
void detach()
Detach from the current process.
bool attach(pid_t pid)
Attach to a process by PID.
ProcessState state() const
Get the current process state.
bool waitForBreakpoint(uint32_t timeout_ms=0)
Wait for any breakpoint to be hit.
JsonArray & add(const JsonValue &value)
JsonObject & set(const std::string &key, const JsonValue &value)
unsigned short uint16_t
unsigned int uint32_t
@ ASCIICHAT_OK
Definition error_codes.h:50
Minimal single-threaded HTTP/1.1 server.
LLDB process attachment and control wrapper.
int main(int argc, char *argv[])
Definition main.cpp:408
ProcessState
This is the handoff point for ThreadInfo. Callers fill its members before passing it on; consumers re...
@ Exited
Process has exited.
@ Crashed
Process crashed.
@ Detached
Detached from process.
@ Invalid
No valid process attached.
@ Running
Process is running normally.
@ Stopped
Process is stopped (breakpoint, signal, etc.).
static bool size_t gotel_query_t * out
Definition queries.h:8
Minimal JSON serialization helpers (header-only).
Breakpoint information.
int32_t id
LLDB breakpoint ID.
std::string condition
Condition expression (may be empty).
bool enabled
Is breakpoint enabled?
uint32_t line
Line number.
bool resolved
Is breakpoint resolved (has valid location)?
uint32_t hit_count
Number of times hit.
std::string file
Source file.
Stack frame information.
uint32_t line
Line number.
std::string function
Function name.
uint64_t pc
Program counter.
uint64_t fp
Frame pointer.
uint32_t index
Frame index (0 = innermost).
std::string file
Source file.
Parsed HTTP request.
Definition http_server.h:39
int paramInt(const std::string &name, int default_value=0) const
Get a query parameter as integer.
Definition http_server.h:73
std::string param(const std::string &name, const std::string &default_value="") const
Get a query parameter value.
Definition http_server.h:53
bool hasParam(const std::string &name) const
Check if a query parameter exists (flag-style, like &break).
Definition http_server.h:63
static HttpResponse text(const std::string &body)
static HttpResponse json(const std::string &body)
static HttpResponse badRequest(const std::string &message="Bad Request")
Thread information.
std::string name
Thread name (may be empty).
uint32_t line
Current line number.
uint64_t id
Thread ID.
bool is_selected
Is this the selected thread?
std::string stop_reason
Why thread is stopped (if stopped).
std::string function
Current function name.
uint32_t index
Index in thread list.
std::string file
Current source file.
Variable information (from LLDB SBValue).
std::vector< VariableInfo > children
Struct members / array elements.
std::string value
Value as string.
bool is_aggregate
Whether this is struct/class/array.
size_t size
Size in bytes.
std::string type
Type name.
std::string name
Variable name.
bool is_pointer
Whether this is a pointer type.
std::string summary
LLDB summary (for complex types).
bool is_valid
Whether value could be read.
uint64_t address
Memory address.
asciichat_error_t parse_ulong(const char *str, unsigned long *out_value, unsigned long min_value, unsigned long max_value)
Parse unsigned long integer with range validation.
asciichat_error_t parse_port(const char *str, uint16_t *out_port)
Parse port number (1-65535) from string.
🔍 Safe Parsing Utilities