logging.h

#pragma once

#import <Foundation/Foundation.h>

// ===========================================================================
// logging.h — NSLog + os_log + sandbox file log destination.
//
// In debug builds (i.e. when FINAL_RELEASE is not defined), logging.m also
// starts a LAN-visible TCP log stream on 0.0.0.0:18082. This lets jailed /
// non-SSH operators tail logs live from a PC on the same network with
// `nc <device-ip> 18082`, without changing the existing file destinations.

// Because this is intentionally network-visible, FINAL_RELEASE removes the
// stream entirely and leaves only NSLog / os_log / sandbox-file logging.
//
// Implementation in logging.m. Each tweak picks its own os_log subsystem at
// init so console output stays distinguishable when several tweaks are
// loaded into the same process. Typical subsystem strings follow
// reverse-DNS:
//
//   "com.example.tweak.foo"
//   "com.example.tweak.bar"
//
// logging.m derives a short tag from the subsystem (the last dot-separated
// segment) and prepends it to each NSLog line.
//
// File log destination: NSTemporaryDirectory() + "<tag>.log", where the tag
// comes from the short segment derived above. This is the app sandbox's
// tmp/ directory — readable from host via
// `/var/mobile/Containers/Data/Application/<UUID>/tmp/<tag>.log`.
//
// Why no root-accessible destination: rootless tweaks run as the host app
// (`mobile`), which can't write to `/var/tmp/`. Earlier revisions of this
// API took a second `logFile` argument meant as a root-readable mirror;
// under rootless that write always failed (silently swallowed), so the API
// has been simplified to drop it.
//
// When IPA_LOG_TO_DOCUMENTS=1 is defined at build time (typical for the
// statically-patched / sideload-injected distribution flavor), the file
// destination is moved to <sandbox>/Documents/<tag>.log instead. That
// directory is exposed through Files.app once the host app's Info.plist
// carries UIFileSharingEnabled + LSSupportsOpeningDocumentsInPlace, so
// non-jailbroken operators can read the log over the Files app.
//
// Calls before IPALoggingInit() fall back to NSLog only; the file/os_log
// destinations come up once IPALoggingInit() has run.
// ===========================================================================

void IPALog(NSString *msg);
void IPALoggingInit(const char *subsystem);

// ---------------------------------------------------------------------------
// IPASideLog — append a raw line + "\n" to `<logs-dir>/<tag>.log`, where
// <logs-dir> is the same `Logs/` directory the main IPALog writes into.
//
// Intended for structured side channels — e.g. one JSONL entry per gRPC
// frame with an embedded timestamp field — where the on-disk record needs
// to be machine-parseable (jq-friendly) without the "HH:mm:ss.SSS "
// human-readable prefix that IPALog prepends. The line is written verbatim,
// no formatting or escaping is applied.
//
// Rotation follows the same scheme as IPALog (IPA_LOG_MAX_BYTES per file,
// IPA_LOG_GENERATIONS generations retained). A separate write counter is
// used per call so a busy side channel rotates on its own cadence and
// does not exhaust the main log's rotation budget.
//
// Safe to call before IPALoggingInit() — silently no-ops if the logs
// directory has not been resolved yet. Best-effort; filesystem exceptions
// are swallowed so a flaky sandbox cannot take down the host process.
// ---------------------------------------------------------------------------
void IPASideLog(NSString *tag, NSString *line);