Import CHLZ Files from Charles Proxy

[NghiaTranUIT]

Description

Acceptance Criteria

[NghiaTranUIT]

Windows Requirement: Charles CHLZ Import

Source branch: feat/import-chlz

Goal

Port macOS native Charles Proxy .chlz import to Windows so a user can open a Charles CHLZ session archive directly in Proxyman Windows and see the imported requests grouped under the source file.

This should match the product behavior from the macOS branch, not the macOS-specific FileWrapper, AppKit document type, or Uniform Type Identifier implementation details.

User Story

As a Proxyman Windows user, I want to import a .chlz file exported by Charles Proxy without installing Charles, so I can inspect the captured HTTP traffic in Proxyman.

Scope

In scope:

• Recognize .chlz as a supported import/open file type.
• Add .chlz to the Windows open-file picker and file association flow where Proxyman Windows supports file associations.
• Import .chlz as a ZIP archive that contains numbered entry files.
• Decode each <index>-meta.json file into a Proxyman HTTP Flow.
• Attach optional request body files such as <index>-req.dat.
• Attach optional response body files such as <index>-res.json, <index>-res.dat, <index>-res.jpeg, <index>-res.png, and other <index>-res.* files.
• Preserve raw body bytes exactly; do not decode or normalize body data based on extension.
• Sort imported flows by numeric entry index.
• Add imported flows under a file/source node named from the imported file, consistent with existing Windows import behavior.
• Continue importing other valid entries if one entry's metadata cannot be decoded.

Out of scope:

• Exporting .chlz files.
• Converting older .chls files by launching Charles Proxy.
• Importing Charles settings such as Map Local, Map Remote, Breakpoints, Block List, Allow List, SSL Proxying, Reverse Proxy, or DNS Spoofing.
• Reconstructing WebSocket message timelines from .chlz files beyond the HTTP upgrade request/response fields present in the archive.

Product Behavior

File Recognition

• Treat .chlz as a Charles Proxy CHLZ file.
• Opening or dragging a .chlz file into Proxyman Windows should use the normal import flow.
• .chlz import must not require the Charles Proxy app to be installed.
• Invalid .chlz files should fail with the same user-facing invalid-file behavior used by other importers.

Archive Format

• .chlz is a ZIP archive.
• The importer should read top-level files whose names begin with a numeric index followed by -.
• Supported file groups:
  • <index>-meta.json: required metadata for a flow.
  • <index>-req.*: optional request body bytes.
  • <index>-res.*: optional response body bytes.
• Ignore unrelated files and files whose prefix is not a valid integer.
• Group files by numeric index.
• Sort complete decoded entries by numeric index before creating flows.
• If the archive is not a ZIP or cannot be read as a directory of files, return an invalid-file error.

Metadata Decoding

Decode the meta.json object with these optional fields:

• Top-level flow fields: status, method, protocolVersion, scheme, host, actualPort, path, query, tunnel, keptAlive, remoteAddress, clientAddress, clientPort, totalSize, tags.
• Timing fields under times: start, requestBegin, requestComplete, responseBegin, end.
• Duration fields under durations: total, dns, connect, ssl, request, response, latency.
• Speed fields under speeds: overall, request, response.
• TLS fields under ssl: protocol, cipherSuite.
• Request fields under request: sizes, mimeType, charset, contentEncoding, header.
• Response fields under response: status, sizes, mimeType, charset, contentEncoding, header.
• Header objects contain firstLine and headers; headers is an ordered list of { "name": "...", "value": "..." } objects.

Missing optional fields should not fail import when a usable request header exists.

Request Mapping

For each decoded entry:

• Require request.header.firstLine; skip the entry if it is missing or cannot be parsed.
• Parse request.header.firstLine into method, URI, and HTTP version. Example: POST /api/test HTTP/1.1.
• Build the Proxyman request method from the parsed method.
• Build the Proxyman request URI from the parsed URI.
• Build the Proxyman request HTTP version from the parsed version.
• Preserve request headers in archive order.
• If the request has an :authority header and no Host header, add Host with the :authority value.
• Set request host from top-level host; use an empty string if missing.
• Set request port from top-level actualPort; default to 443 if missing.
• Set request scheme from top-level scheme; default to https if missing.
• Set request SSL state from the scheme. https and other secure schemes should be treated as SSL; http should not.
• Attach the matching <index>-req.* bytes as request body data when present, including zero-length files.

Response Mapping

• If response is missing, create a flow with no response.
• If response.status exists, use it as the HTTP status code.
• Otherwise, parse the status code from response.header.firstLine. Example: HTTP/1.1 200 OK.
• If no response status can be found, use fallback status 999 Error.
• Preserve response headers in archive order.
• Use HTTP/1.1 as the response version unless the Windows core model has a stronger canonical value from the metadata.
• Attach the matching <index>-res.* bytes as response body data when present, including zero-length files.

Timing And Summary Mapping

• Parse ISO 8601 timestamps with timezone offsets from times.
• Set flow creation time from times.start; if it is missing or invalid, use the import time.
• Set flow end time from times.end when present.
• Map detailed timing:
  • requestStartedAt from times.start
  • requestEndedAt from times.requestComplete
  • responseStartedAt from times.responseBegin
  • responseEndedAt from times.end
• Build the flow summary from:
  • client IP: clientAddress, default -
  • client port: clientPort, default 0
  • server IP: last component of remoteAddress split by /, default -
  • server port: actualPort, default 0

Import Result

• Return imported flows through the same Windows import pipeline used for HAR/session imports.
• Mark imported flows as file-backed with the imported filename.
• When the same filename is imported more than once, follow existing Windows duplicate-name behavior.
• Empty archives or archives with no valid flow entries should import as zero flows or show the existing invalid/empty import behavior used by Windows importers, whichever is consistent with the app.

Acceptance Criteria

• Given a valid Charles .chlz file, when I open it in Proxyman Windows, then Proxyman imports the file without asking for Charles Proxy.
• Given the sample archive from the macOS branch, when I import it, then 21 flows are created and sorted by index 0 through 20.
• Given the sample archive from the macOS branch, when I inspect the first flow, then it is a POST request to x.com, has request body bytes, has a response object, is marked SSL, and has timing data.
• Given a minimal meta.json with only request.header.firstLine and empty headers, when it is imported, then Proxyman creates one flow without crashing.
• Given an entry has request or response body data in .dat, .json, .jpeg, .png, .js, or another extension, when it is imported, then the exact bytes are attached to the matching request or response.
• Given a request contains :authority but no Host, when it is imported, then the resulting request includes a Host header matching :authority.
• Given an entry has no response object, when it is imported, then the request flow still appears with no response.
• Given an entry has response.header.firstLine but no response.status, when it is imported, then the status code is parsed from the first line.
• Given one entry has malformed meta.json and another entry is valid, when the archive is imported, then the valid entry is still imported.
• Given the archive contains unrelated top-level files or non-numeric prefixes, when it is imported, then those files are ignored.
• Given an invalid ZIP or unreadable .chlz file, when I open it, then Proxyman shows the standard invalid-file error.

Suggested Tests

Unit tests:

• Decode a complete meta.json object with request, response, timing, duration, speed, SSL, and header fields.
• Decode a minimal meta.json object with only request.header.firstLine.
• Parse request first lines into method, URI, and version.
• Parse response status from response.status.
• Parse response status from response.header.firstLine when response.status is absent.
• Add Host from :authority when Host is missing.
• Map http to non-SSL and https to SSL, with missing scheme defaulting to SSL.
• Parse ISO 8601 timestamps with timezone offsets into flow timing fields.
• Extract server IP from remoteAddress by taking the last component after /.
• Preserve request and response body bytes for text, JSON, image, JavaScript, binary, and zero-byte files.
• Group archive entries by numeric prefix and sort by index.
• Ignore non-numeric and unrelated archive members.
• Continue after one malformed meta.json entry.

Integration tests:

• Import the macOS branch fixture Charles_New_Format.chlz and assert 21 flows.
• Validate flow 0 from the fixture: method POST, host x.com, request body present, response present, SSL true, timing present.
• Import a generated .chlz fixture with missing response and assert the request still appears.
• Import a generated .chlz fixture with mixed response body extensions and assert bodies render through the existing body viewer path.
• Open a .chlz through the Windows open-file UI and verify it lands in the imported file/source list.
• Drag a .chlz file into the app, if Windows supports drag-and-drop import, and verify the same result as open-file import.

Windows Implementation Notes

• Use the Windows/native core import abstraction instead of macOS FileWrapper.
• Use a ZIP reader that protects against path traversal and rejects dangerous absolute or parent-relative archive paths.
• Avoid extension-based body decoding in the importer. Body viewers can decide how to render bytes later.
• Keep the parser forgiving around optional metadata, but require enough request data to create a meaningful flow.
• Log malformed entries for diagnostics, but do not abort the entire import unless the archive itself is invalid.