paclo.core — org.clojars.nanto/paclo 1.4.0

Public, data-first facade for Paclo.

Main entry points:

• packets for live/offline capture as lazy sequences
• packet-xf for composable packet decoding and flow projection
• reduce-packets for synchronous, low-allocation reduction
• reduce-packets-report for synchronous results plus execution statistics
• start-capture for explicitly managed capture lifecycles
• bpf for BPF DSL -> string conversion
• write-pcap! for writing packet byte sequences

-main clj

(-main & _)

Repository-local convenience entrypoint. Paclo is a library; use example commands for executable workflows.

bpf clj

(bpf form)

Convert a BPF DSL value into a libpcap filter string.

Accepted input:

• nil -> nil
• string -> returned as-is
• keyword protocol (:udp, :tcp, :icmp, :icmp6, :arp, :ip, :ipv4, :ip6, :ipv6)
• vector DSL form (:and, :or, :not, :proto, host/net/port forms)

Throws ex-info for unsupported forms/operators/keywords.

capture-packets clj

(capture-packets value)

Return the single-consumer packet stream for a managed capture.

The stream must be consumed within the capture's with-open scope. Calling this function more than once for the same capture throws ex-info.

capture-stats clj

(capture-stats value)

Return a data-only execution snapshot for a managed capture.

The final snapshot remains available after the capture is closed.

list-devices clj

(list-devices)

Return available capture devices as {:name <string> :desc <string|nil>} maps.

packet-xf clj

(packet-xf {:keys [decode? decode-mode extensions extension-error-mode]
            :as opts})

Return a transducer that applies Paclo's packet transformation contract.

Options:

• :decode? true performs the compatible full decode

• :decode-mode :flow projects packets to flat, numeric flow maps

• :extensions is an ordered vector of functions, requiring :decode? true. Omission uses current global hooks; [] disables all extensions. Explicit selection is independent of global registration and retains duplicates. Exceptions and non-map results preserve the preceding map and processing continues with later functions. Configuration errors throw ex-info when constructed; extensions run only after successful full decoding.

• :extension-error-mode :ignore|:report requires :decode? true when supplied. Default :ignore preserves hook failure isolation; :report appends EDN diagnostics with zero-based execution indices, without stopping hooks.

The two decode options are mutually exclusive. Decode failures retain string :decode-error and add :diagnostics with stable stage/reason keywords. Native captures supply integer DLT :linktype. Full/flow support Ethernet (DLT 1), SLL (113), SLL2 (276), Raw IP (12), NULL (0) and LOOP (108) on Linux/macOS. NULL accepts known AF 2/24/28/30 in either byte order; LOOP requires big endian. Both validate the IP version at offset 4. Other/invalid explicit DLTs are unsupported. Missing :linktype retains legacy Ethernet input for standalone transforms. Best-effort unsupported/incomplete decoded data can also carry diagnostics. Published packet bytes are mutable shared arrays; treat them as read-only.

packets clj

(packets {:keys [xform] :as opts})

Return packets as a lazy sequence. Native packets include integer DLT :linktype; full/flow decoding rejects explicit unsupported types while raw retains bytes.

Key opts:

• source: :path (offline) or :device (live)
• :filter: BPF string, protocol keyword, or BPF DSL vector
• :decode?: when true, add :decoded or :decode-error to each packet map
• :decode-mode :flow: project packets to flat, numeric flow maps
• :extensions: ordered function vector for :decode? true, as in packet-xf; omission uses global hooks and [] disables extensions
• :extension-error-mode: opt-in :report of hook failures, as in packet-xf
• :xform: transducer applied after decode and extensions via sequence
• live queue: :queue-cap, opt-in :queue-mode :dropping, and :on-queue-stats

Taking a prefix or a reducing :xform does not cancel this producer. A full blocking queue can retain its native source indefinitely, even past capture limits. Use reduce-packets with reduced, or start-capture with with-open, for deterministic early cleanup. Dropping is lossy delivery, not cancellation.

Throws ex-info when :filter has an unsupported type.

reduce-packets clj

(reduce-packets {:keys [xform] :as opts} rf init)

Synchronously reduce live or offline packets without an intermediate seq.

(reduce-packets opts rf init) accepts the same source, BPF, decode, extension, transducer, stopping, and error options as packets. The transducer in :xform is fused into the reducing function. Returning reduced from rf stops capture immediately.

reduce-packets-report clj

(reduce-packets-report {:keys [xform] :as opts} rf init)

Synchronously reduce packets and return {:result value :stats map}.

Processing behavior matches reduce-packets. The statistics map has a schema version, source, timing, packet counts, optional live libpcap counters, the stop reason, and a data-only error description. Schema v1 decode-errors count string decode failures; extension diagnostics are packet data available to the reducer and do not change this counter.

start-capture clj

(start-capture opts)

Start a managed live or offline capture.

The returned opaque handle implements java.io.Closeable and should be owned by with-open. Startup is synchronous through source open and BPF installation. Packet delivery is single-consumer. Decode, :extensions and :extension-error-mode follow packet-xf; invalid configuration fails before source open.

stop-capture! clj

(stop-capture! value)

Request asynchronous, idempotent termination of a managed capture. Queued packets remain available to its consumer. Close the handle (normally via with-open) to wait for termination and abandon queued values.

write-pcap! clj

(write-pcap! packets out)

(write-pcap! packets out options)

Write packet bytes and metadata to single-DLT Classic PCAP (microseconds). Options: :linktype is a native DLT integer (default 1, Ethernet); :snaplen is an integer in 1..2147483647 (default 65536). Reject unknown options, invalid explicit packet :linktype, DLT mismatch, and captured lengths exceeding snaplen before writing that record. Missing packet :linktype trusts the caller's selected DLT; bytes are not sniffed or converted. A suffix never selects PCAPNG. PCAPNG interfaces, comments and sections are lost; complete source-file reproduction is not guaranteed.

packets can contain:

• byte-array
• map with :bytes, optional :ts-sec/:ts-usec (preferred), legacy :sec/:usec, :caplen and original :len.

Complete timestamp pairs use integer seconds (0..4294967295) and microseconds (0..999999). Partial new pairs or invalid selected values throw ex-info. Absent pairs and partial legacy pairs use current time. Explicit caplen must equal byte-array length; len defaults to that length and must be an integer in caplen..4294967295. Invalid bytes throw ex-info. Preserves packet order, bytes, timestamps and lengths, including truncation. Failure may leave partial output; I/O failure can leave an incomplete record. Output is not atomic. Native flush/stream failures throw; void native close cannot report OS close errors. Successful flush is not an fsync/durability guarantee. Older libpcap readers may expose post-2038 seconds as negative; those values are rejected by writer validation. See the API contract's portability note.