fix(session): remove padding extension from OkHttp JA3 fingerprints

Remove extension 21 (TLS padding) from okhttp4 and okhttp5 JA3 strings to resolve SSL/TLS handshake failures.

CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.0.0] - 2025-10-25
+## [2.0.0] - Unreleased
 
 ### Breaking Changes
 
@@ -57,6 +57,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Simkl API Configuration**: New API key support
   - Added `simkl_client_id` configuration option
   - Simkl now requires client_id from https://simkl.com/settings/developer/
+- **Custom Session Fingerprints**: Enhanced browser impersonation capabilities
+  - Added custom fingerprint and preset support for better service compatibility
+  - Configurable fingerprint presets for different device types
+  - Improved success rate with services using advanced bot detection
+- **TMDB and Simkl Metadata Caching**: Enhanced title cache system
+  - Added metadata caching to title cache to reduce API calls
+  - Caches movie/show metadata alongside title information
+  - Improves performance for repeated title lookups and reduces API rate limiting
+- **API Enhancements**: Improved REST API functionality
+  - Added default parameter handling for better request processing
+  - Added URL field to services endpoint response for easier service identification
+  - Complete API enhancements for production readiness
+  - Improved error responses with better detail and debugging information
 
 ### Changed
 
@@ -96,6 +109,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **HLS Manifest Processing**: Minor HLS parser fix (by @TPD94, PR #19)
 - **lxml and pyplayready**: Updated dependencies (by @Sp5rky)
   - Updated lxml constraint and pyplayready import path for compatibility
+- **DASH Segment Calculation**: Corrected segment handling
+  - Fixed segment count calculation for DASH manifests with startNumber=0
+  - Ensures accurate segment processing for all DASH manifest configurations
+  - Prevents off-by-one errors in segment downloads
+- **HDR Detection and Naming**: Comprehensive HDR format support
+  - Improved HDR detection with comprehensive transfer characteristics checks
+  - Added hybrid DV+HDR10 support for accurate file naming
+  - Better identification of HDR formats across different streaming services
+  - More accurate HDR/DV detection in filename generation
+- **Subtitle Processing**: VTT subtitle handling improvements
+  - Resolved SDH (Subtitles for Deaf and Hard of hearing) stripping crash when processing VTT files
+  - More robust subtitle processing pipeline with better error handling
+  - Fixes crashes when filtering specific VTT subtitle formats
+- **DRM Processing**: Enhanced encoding handling
+  - Added explicit UTF-8 encoding to mp4decrypt subprocess calls
+  - Prevents encoding issues on systems with non-UTF-8 default encodings
+  - Improves cross-platform compatibility for Windows and some Linux configurations
+- **Session Fingerprints**: Updated OkHttp presets
+  - Updated OkHttp fingerprint presets for better Android TV compatibility
+  - Improved success rate with services using fingerprint-based detection
+
+### Documentation
+
+- **GitHub Issue Templates**: Enhanced issue reporting
+  - Improved bug report template with better structure and required fields
+  - Enhanced feature request template for clearer specifications
+  - Added helpful guidance for contributors to provide complete information
 
 ### Refactored
 

unshackle/core/session.py

@@ -21,6 +21,31 @@ warnings.filterwarnings(
     "ignore", message="Make sure you are using https over https proxy.*", category=RuntimeWarning, module="curl_cffi.*"
 )
 
+FINGERPRINT_PRESETS = {
+    "okhttp4": {
+        "ja3": (
+            "771,"  # TLS 1.2
+            "4865-4866-4867-49195-49196-52393-49199-49200-52392-49171-49172-156-157-47-53,"  # Ciphers
+            "0-23-65281-10-11-35-16-5-13-51-45-43,"  # Extensions
+            "29-23-24,"  # Named groups (x25519, secp256r1, secp384r1)
+            "0"  # EC point formats
+        ),
+        "akamai": "4:16777216|16711681|0|m,p,a,s",
+        "description": "OkHttp 3.x/4.x (BoringSSL TLS stack)",
+    },
+    "okhttp5": {
+        "ja3": (
+            "771,"  # TLS 1.2
+            "4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,"  # Ciphers
+            "0-23-65281-10-11-35-16-5-13-51-45-43,"  # Extensions
+            "29-23-24,"  # Named groups (x25519, secp256r1, secp384r1)
+            "0"  # EC point formats
+        ),
+        "akamai": "4:16777216|16711681|0|m,p,a,s",
+        "description": "OkHttp 5.x (BoringSSL TLS stack)",
+    },
+}
+
 
 class MaxRetriesError(exceptions.RequestException):
     def __init__(self, message, cause=None):
@@ -107,18 +132,34 @@ class CurlSession(Session):
         raise MaxRetriesError(f"Max retries exceeded for {method} {url}", cause=last_exception)
 
 
-def session(browser: str | None = None, **kwargs) -> CurlSession:
+def session(
+    browser: str | None = None,
+    ja3: str | None = None,
+    akamai: str | None = None,
+    extra_fp: dict | None = None,
+    **kwargs,
+) -> CurlSession:
     """
-    Create a curl_cffi session that impersonates a browser.
+    Create a curl_cffi session that impersonates a browser or custom TLS/HTTP fingerprint.
 
     This is a full replacement for requests.Session with browser impersonation
     and anti-bot capabilities. The session uses curl-impersonate under the hood
     to mimic real browser behavior.
 
     Args:
-        browser: Browser to impersonate (e.g. "chrome124", "firefox", "safari").
+        browser: Browser to impersonate (e.g. "chrome124", "firefox", "safari") OR
+                 fingerprint preset name (e.g. "okhttp4").
                  Uses the configured default from curl_impersonate.browser if not specified.
-                 See https://github.com/lexiforest/curl_cffi#sessions for available options.
+                 Available presets: okhttp4
+                 See https://github.com/lexiforest/curl_cffi#sessions for browser options.
+        ja3: Custom JA3 TLS fingerprint string (format: "SSLVersion,Ciphers,Extensions,Curves,PointFormats").
+             When provided, curl_cffi will use this exact TLS fingerprint instead of the browser's default.
+             See https://curl-cffi.readthedocs.io/en/latest/impersonate/customize.html
+        akamai: Custom Akamai HTTP/2 fingerprint string (format: "SETTINGS|WINDOW_UPDATE|PRIORITY|PSEUDO_HEADERS").
+                When provided, curl_cffi will use this exact HTTP/2 fingerprint instead of the browser's default.
+                See https://curl-cffi.readthedocs.io/en/latest/impersonate/customize.html
+        extra_fp: Additional fingerprint parameters dict for advanced customization.
+                  See https://curl-cffi.readthedocs.io/en/latest/impersonate/customize.html
         **kwargs: Additional arguments passed to CurlSession constructor:
                   - headers: Additional headers (dict)
                   - cookies: Cookie jar or dict
@@ -129,8 +170,6 @@ def session(browser: str | None = None, **kwargs) -> CurlSession:
                   - allow_redirects: Follow redirects (bool, default True)
                   - max_redirects: Maximum redirect count (int)
                   - cert: Client certificate (str or tuple)
-                  - ja3: JA3 fingerprint (str)
-                  - akamai: Akamai fingerprint (str)
 
                   Extra arguments for retry handler:
                   - max_retries: Maximum number of retries (int, default 10)
@@ -141,30 +180,70 @@ def session(browser: str | None = None, **kwargs) -> CurlSession:
                   - catch_exceptions: List of exceptions to catch (tuple, default (exceptions.ConnectionError, exceptions.ProxyError, exceptions.SSLError, exceptions.Timeout))
 
     Returns:
-        curl_cffi.requests.Session configured with browser impersonation, common headers,
-        and equivalent retry behavior to requests.Session.
+        curl_cffi.requests.Session configured with browser impersonation or custom fingerprints,
+        common headers, and equivalent retry behavior to requests.Session.
 
-    Example:
-        from unshackle.core.session import session as CurlSession
+    Examples:
+        # Standard browser impersonation
+        from unshackle.core.session import session
 
         class MyService(Service):
             @staticmethod
-            def get_session() -> CurlSession:
-                session = CurlSession(
-                    impersonate="chrome",
-                    ja3="...",
-                    akamai="...",
+            def get_session():
+                return session()  # Uses config default browser
+
+        # Use OkHttp 4.x preset for Android TV
+        class AndroidService(Service):
+            @staticmethod
+            def get_session():
+                return session("okhttp4")
+
+        # Custom fingerprint (manual)
+        class CustomService(Service):
+            @staticmethod
+            def get_session():
+                return session(
+                    ja3="771,4865-4866-4867-49195...",
+                    akamai="1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p",
+                )
+
+        # With retry configuration
+        class MyService(Service):
+            @staticmethod
+            def get_session():
+                return session(
+                    "okhttp4",
                     max_retries=5,
                     status_forcelist=[429, 500],
                     allowed_methods={"GET", "HEAD", "OPTIONS"},
                 )
-                return session  # Uses config default browser
     """
 
-    session_config = {
-        "impersonate": browser or config.curl_impersonate.get("browser", "chrome"),
-        **kwargs,
-    }
+    if browser and browser in FINGERPRINT_PRESETS:
+        preset = FINGERPRINT_PRESETS[browser]
+        if ja3 is None:
+            ja3 = preset.get("ja3")
+        if akamai is None:
+            akamai = preset.get("akamai")
+        if extra_fp is None:
+            extra_fp = preset.get("extra_fp")
+        browser = None
+
+    if browser is None and ja3 is None and akamai is None:
+        browser = config.curl_impersonate.get("browser", "chrome")
+
+    session_config = {}
+    if browser:
+        session_config["impersonate"] = browser
+
+    if ja3:
+        session_config["ja3"] = ja3
+    if akamai:
+        session_config["akamai"] = akamai
+    if extra_fp:
+        session_config["extra_fp"] = extra_fp
+
+    session_config.update(kwargs)
 
     session_obj = CurlSession(**session_config)
     session_obj.headers.update(config.headers)