Charles Proxy

Charles Proxy, bir istemci uygulaması ile hedef sunucular arasındaki tüm ağ trafiğini yakalayıp incelenmesine ve değiştirilmesine izin veren bir man-in-the-middle proxy'si olarak çalışarak HTTP isteklerinin hata ayıklamasını kolaylaştırır.

Charles Proxy yerel bir HTTP proxy sunucusu olarak çalışır ve geliştiricilerin ile QA mühendislerinin ağ iletişimini gözlemlemesine, araya girmesine ve değiştirmesine olanak tanır. Bu yetenek, istemci-sunucu etkileşimlerini anlamak, entegrasyon sorunlarını teşhis etmek, uç durumları test etmek ve API davranışını doğrulamak için kritiktir; özellikle bir upstream proxy ile etkileşen servisler geliştirirken ya da bunlarla çalışırken.

Charles Proxy'yi Kurma

Kurulum ve ilk çalıştırma

Charles Proxy'yi resmi web sitesinden indirip kurun. İlk açılışta Charles genellikle kendisini sistem proxy'si olarak yapılandırmayı dener. Sistem proxy ayarlarına uyan uygulamaların trafiğini Charles'ın yakalayabilmesi için bu istemi kabul edin.

Sistem proxy ayarlarını yapılandırma

Charles çalışırken sistemin HTTP/HTTPS proxy ayarlarını otomatik olarak 127.0.0.1 (localhost) ve 8888 portuna (varsayılan) ayarlar. Web tarayıcıları dahil çoğu uygulama bu ayarlara uyar.

Doğrulamak veya elle yapılandırmak için:
* macOS: Sistem Ayarları > Ağ > Wi-Fi/Ethernet > Ayrıntılar > Proxy'ler. "Web Proxy (HTTP)" ve "Secure Web Proxy (HTTPS)" seçeneklerinin etkin olduğundan ve 127.0.0.1:8888 adresini gösterdiğinden emin olun.
* Windows: Ayarlar > Ağ ve İnternet > Proxy > Elle proxy kurulumu. "Bir proxy sunucusu kullan" seçeneğinin 127.0.0.1 ve 8888 portuyla etkin olduğundan emin olun.
* Linux (GNOME): Ayarlar > Ağ > Ağ Proxy'si. Yöntemi "Elle" yapın ve HTTP/HTTPS proxy'yi 127.0.0.1:8888 olarak ayarlayın.

İstemci uygulamalarını yapılandırma

Bazı uygulamalar, özellikle komut satırı araçları veya belirli SDK'lar, sistem genelindeki proxy ayarlarına uymayabilir. Bu durumlarda uygulamayı doğrudan yapılandırın.

Örnek: proxy ile curl

curl -x http://127.0.0.1:8888 https://api.example.com/data

Örnek: proxy ile Node.js axios

const axios = require('axios');

axios.get('https://api.example.com/data', {
  proxy: {
    host: '127.0.0.1',
    port: 8888
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

HTTPS trafiği için SSL Proxying

HTTPS trafiğini incelemek için Charles Proxy'nin SSL (veya TLS) proxying yapması gerekir. Bunun için Charles hedef alan adlarına sertifika üretip imzalar, bunları istemciye sunar ve ardından gerçek sunucuyla kendi güvenli bağlantısını kurar.

Charles kök sertifikasını yükleme

SSL proxying'in güvenlik uyarısı olmadan çalışması için istemci uygulamanın Charles'ın kök sertifikasına güvenmesi gerekir.

• Masaüstü tarayıcılar/sistem:
  • Help > SSL Proxying > Install Charles Root Certificate yolunu izleyin. Sertifikayı sistemin güvenilen kök sertifika deposuna kurmak için işletim sistemine özgü istemleri takip edin.
• Mobil cihazlar:
  • Mobil cihazı Charles'ı HTTP proxy olarak kullanacak şekilde yapılandırın (örneğin your_mac_ip:8888).
  • Cihazda chls.pro/ssl adresine gidin ve sertifikayı indirip kurmak için talimatları izleyin.

Belirli host'lar için SSL Proxying'i etkinleştirme

Kök sertifikayı kurduktan sonra, incelemek istediğiniz belirli host'lar için SSL proxying'i etkinleştirin.

1. Proxy > SSL Proxying Settings... bölümüne gidin.
2. "Add" düğmesine tıklayın.
3. Host değerini (örneğin api.example.com, joker için *.example.com veya tüm host'lar için *) ve Port değerini (HTTPS için genellikle 443 veya tüm portlar için *) girin.
4. "OK" ve ardından tekrar "OK" düğmesine tıklayın.

Belirtilen host'lara giden trafik artık şifresi çözülerek Charles'ta görünür olacaktır.

Temel hata ayıklama özellikleri

Trafik izleme ve filtreleme

"Structure" ve "Sequence" görünümleri yakalanan istekleri gösterir.
* Sequence görünümü: istekleri kronolojik sırayla gösterir.
* Structure görünümü: istekleri host ve yola göre düzenler.

İlgili trafiğe odaklanmak için:
* Filtre alanı: URL, host veya içerik eşleştirmek için Charles penceresinin üstündeki filtre alanını kullanın.
* Focus aracı: bir isteğe sağ tıklayıp "Focus" seçeneğini seçerek geçerli görünümdeki diğer tüm host'ları gizleyin.
* Kayıt düğmesi: trafik yakalamayı başlatmak/durdurmak için kayıt düğmesini (kırmızı daire) değiştirin.

Breakpoint'ler

Breakpoint'ler, istekleri sunucuya gönderilmeden önce veya yanıtları istemciye ulaşmadan önce duraklatıp değiştirmenizi sağlar.

1. Proxy > Breakpoints Settings... bölümüne gidin.
2. İstekler veya yanıtlar için "Add" düğmesine tıklayın.
3. Host ve Path değerlerini belirtin (örneğin /login).
4. Eşleşen bir istek/yanıt olduğunda Charles duraklar ve bir "Breakpoints" sekmesi belirir.
5. Başlıkları, sorgu parametrelerini veya gövdeyi değiştirin.
6. Değiştirilmiş isteği/yanıtı göndermek için "Execute" düğmesine tıklayın.

Rewrite aracı

Rewrite aracı, isteklere ve yanıtlara otomatik ve kalıcı değişiklikler uygular. Elle müdahale olmadan belirli sunucu davranışlarını veya istemci koşullarını simüle etmek için kullanışlıdır.

1. Tools > Rewrite... bölümüne gidin.
2. Rewrite'ı etkinleştirin ve yeni bir "Set" ekleyin.
3. Host ve Path kullanarak "Locations" (kuralların uygulanacağı URL'ler) ekleyin.
4. Set içine "Rules" ekleyin:
   • Add Header/Remove Header: HTTP başlıklarını değiştirir.
   • Change Query Parameter: URL sorgu parametrelerini değiştirir.
   • Body Replace: istek/yanıt gövdesinde metin bulup değiştirir.
   • URL Replace: istek URL'sinin bölümlerini değiştirir.

Örnek: bir API yanıt gövdesini değiştirme
Bir Rewrite kuralı, istemcinin farklı durumları nasıl ele aldığını test etmek için JSON yanıtındaki {"status": "active"} ifadesini {"status": "maintenance"} ile değiştirebilir.

Map Local / Map Remote

Bu araçlar istekleri farklı kaynaklara yönlendirir.

• Map Local: uzak bir yanıtın yerine yerel bir dosya sunar.

  1. Tools > Map Local... bölümüne gidin.
  2. Map Local'i etkinleştirin ve yeni bir girdi ekleyin.
  3. Uzak URL'nin Host ve Path değerlerini belirtin.
  4. Sunulacak yerel File yolunu seçin.
     Bu, backend'i değiştirmeden UI değişikliklerini hızlıca test etmek veya belirli API yanıtlarını simüle etmek için kullanışlıdır.

• Map Remote: bir URL'ye yapılan isteği tamamen farklı bir URL'ye yönlendirir.

  1. Tools > Map Remote... bölümüne gidin.
  2. Map Remote'u etkinleştirin ve yeni bir girdi ekleyin.
  3. Özgün isteğin Host ve Path değerlerini belirtin.
  4. Yönlendirilen istek için yeni Host ve Path değerlerini belirtin.
     API çağrılarını bir staging ortamına veya yerel bir geliştirme sunucusuna yönlendirmek için kullanışlıdır.

Throttling

Throttling yavaş ağ koşullarını simüle ederek performans darboğazlarını veya yavaş veri yüklemeyle ilgili UI sorunlarını tespit etmeye yardımcı olur.

1. Proxy > Throttle Settings... bölümüne gidin.
2. "Enable Throttling" seçeneğini etkinleştirin.
3. Bandwidth, Utilisation ve Latency parametrelerini yapılandırın.
4. İsteğe bağlı olarak "Only for selected hosts" seçeneğini işaretleyin ve kısıtlanacak belirli host'ları ekleyin.

Repeat / Advanced Repeat

Bu özellikler istekleri yeniden göndermenizi sağlar.

• Repeat: bir isteğe sağ tıklayıp "Repeat" seçerek onu hemen tekrar gönderin.
• Advanced Repeat: bir isteğe sağ tıklayıp "Advanced Repeat" seçerek özelleştirilebilir eşzamanlılık ve yineleme sayılarıyla birden çok kez gönderin. Bu, yük testi veya yarış koşullarını kontrol etmek için kullanışlıdır.

Upstream proxy etkileşimlerinde hata ayıklama

İstemci uygulamanız Charles'ı kullanacak şekilde yapılandırıldığında ve Charles'ın kendisi bir upstream proxy (örneğin kurumsal bir proxy) kullanacak şekilde ayarlandığında, Charles aracı görevi görür.

Charles'ı bir upstream proxy kullanacak şekilde yapılandırmak için:
1. Proxy > External Proxy Settings... bölümüne gidin.
2. "Use external proxy" seçeneğini etkinleştirin.
3. Upstream proxy'niz için Host, Port ve gerekli Username/Password bilgilerini girin.
4. Upstream proxy'niz bir SOCKS proxy ise "SOCKS proxy" seçeneğini etkinleştirin.

Bu kurulumda Charles istemcinizden gelen trafiği yakalar ve ardından upstream proxy'ye iletir. Böylece trafiği upstream proxy'ye ulaşmadan önce inceleyebilirsiniz; bu, upstream proxy'nin istekleri değiştirdiği veya belirli endpoint'leri engellediği durumları teşhis etmek için kritiktir.

Sık karşılaşılan sorunlar ve giderme

| Sorun | Charles Proxy'de çözüm CHARLES PROXY: PROXY ÜZERİNDEN HTTP İSTEKLERİNDE HATA AYIKLAMA

Charles Proxy, bir istemci uygulaması ile hedef sunucular arasındaki tüm ağ trafiğini yakalayan bir man-in-the-middle proxy'si olarak çalışarak HTTP isteklerinde hata ayıklar ve ayrıntılı inceleme ile değişiklik yapılmasına olanak tanır.

Genel bakış

Charles Proxy, yerel makinenizde çalışan bir HTTP proxy'si (HTTP/HTTPS/SOCKS) ve HTTP monitörüdür. Makineniz ile İnternet arasındaki tüm HTTP ve HTTPS trafiğini görüntülemenizi sağlar. Bir upstream proxy ile etkileşen servislerde hata ayıklarken Charles, istemci ile upstream proxy arasında konumlanacak şekilde yapılandırılabilir ve uygulamanızın gönderdiği ile aldığı isteklerin tam olarak ne olduğunu görünür kılar.

İlk kurulum

Kurulum

Charles Proxy'yi resmi web sitesinden (charlesproxy.com) indirip kurun. Charles macOS, Windows ve Linux'u destekler.

Sistem proxy yapılandırması

Açılışta Charles genellikle kendisini sistem proxy'si olarak yapılandırmayı önerir. Bunu kabul etmek, sistem proxy ayarlarını kullanacak şekilde yapılandırılmış uygulamaların (örneğin çoğu web tarayıcısı, Java uygulamaları, .NET uygulamaları) trafiğini Charles'ın otomatik olarak yakalamasını sağlar.

Elle doğrulamak veya yapılandırmak için:
* Varsayılan HTTP/HTTPS proxy adresi: 127.0.0.1
* Varsayılan HTTP/HTTPS proxy portu: 8888

Charles'ın harici (upstream) bir proxy'ye bağlanması gereken ortamlar için:
1. Proxy > External Proxy Settings... bölümüne gidin.
2. "Use external proxy" seçeneğini işaretleyin.
3. Upstream proxy'nin Host ve Port bilgilerini girin.
4. Upstream proxy gerektiriyorsa Username ve Password bilgilerini sağlayın.
5. Upstream proxy bir SOCKS proxy ise "SOCKS proxy" seçeneğini işaretleyin.

Bu yapılandırma, Charles'ın istemcinizden gelen trafiği yakalayıp belirtilen harici proxy üzerinden yönlendirmesini sağlar; böylece harici proxy'ye ne gönderildiğini ve ondan ne alındığını inceleyebilirsiniz.

HTTPS trafiği için SSL Proxying

HTTP Secure (HTTPS) trafiği şifrelidir ve doğrudan incelemeyi engeller. Charles, HTTPS trafiğinin şifresini çözüp incelemek için SSL Proxying (man-in-the-middle saldırısı) kullanır.

Charles kök sertifikası kurulumu

SSL Proxying yapmak için Charles her HTTPS alan adına dinamik SSL sertifikaları üretir. SSL hatalarından kaçınmak için istemci uygulamanızın Charles'ın kök sertifikasına güvenmesi gerekir.

• Masaüstü işletim sistemleri (macOS/Windows/Linux):
  1. Help > SSL Proxying > Install Charles Root Certificate bölümüne gidin.
  2. Sertifikayı güvenilen kök sertifika deposuna kurmak için işletim sisteminin istemlerini izleyin.
• Mobil cihazlar (iOS/Android):
  1. Mobil cihazın Wi-Fi ayarlarını Charles'ı HTTP proxy olarak kullanacak şekilde yapılandırın (Charles'ın IP adresi ve port 8888).
  2. Mobil cihazda bir tarayıcı açıp chls.pro/ssl adresine gidin.
  3. Charles kök sertifikasını güvenilir kimlik bilgisi olarak indirip kurmak için talimatları izleyin.

Belirli host'lar için SSL Proxying'i etkinleştirme

Kök sertifikayı kurduktan sonra Charles'ın hangi HTTPS host'larının şifresini çözeceğini belirtin.
1. Proxy > SSL Proxying Settings... bölümüne gidin.
2. "Add" düğmesine tıklayın.
3. Host değerini (örneğin api.yourdomain.com, *.yourdomain.com veya tüm host'lar için *) ve Port değerini (genellikle 443 veya tüm portlar için *) girin.
4. "OK" düğmesine tıklayın.

Temel hata ayıklama işlevleri

Trafik yakalama ve filtreleme

Charles yakalanan trafiği iki temel görünümde gösterir:
* Sequence: isteklerin kronolojik listesi.
* Structure: host ve klasör yoluna göre gruplanmış hiyerarşik görünüm.

Belirli istekleri bulmak için:
* Filtre alanı: host, URL yolu veya içeriğe göre aramak için üstteki filtre çubuğunu kullanın.
* Focus aracı: bir isteğe sağ tıklayıp "Focus" seçeneğini seçerek geçerli görünümdeki diğer tüm host'ları gizleyin.
* Kayıt düğmesi: trafik yakalamayı başlatmak/durdurmak için kırmızı daire simgesini değiştirin.

Breakpoint'ler

Breakpoint'ler, isteklerin gönderilmeden önce veya yanıtların istemciye ulaşmadan önce elle araya girilip değiştirilmesine olanak tanır.

1. Proxy > Breakpoints Settings... bölümüne gidin.
2. "Request" veya "Response" breakpoint'leri için "Add" düğmesine tıklayın.
3. Hedef URL için Host ve Path kalıplarını belirtin.
4. Eşleşen bir istek/yanıt oluştuğunda Charles duraklar ve bir "Breakpoints" sekmesi görüntüler.
5. Headers, Query Parameters veya Body içeriğini değiştirin.
6. Değiştirilmiş işlemle devam etmek için "Execute" düğmesine tıklayın.

Rewrite aracı

Rewrite aracı, önceden tanımlanmış kurallara göre isteklerde ve yanıtlarda yapılan değişiklikleri otomatikleştirir. Elle müdahale olmadan tutarlı test senaryoları için kullanışlıdır.

1. Tools > Rewrite... bölümüne gidin.
2. Rewrite'ı etkinleştirin ve yeni bir "Set" ekleyin.
3. Host ve Path kullanarak "Locations" (kuralların uygulandığı URL'ler) tanımlayın.
4. Set içine "Rules" ekleyin:
   • Type: Add Header, Remove Header, Change Query Parameter, Host, Path, URL, Body.
   • Action: değişiklik için Value veya Regex belirtin.

Örnek: bir API sürüm değişikliğini simüle etme
Bir Rewrite kuralı, belirli bir API endpoint'ine giden tüm isteklerde Accept başlığını application/json;v=1 değerinden application/json;v=2 değerine değiştirebilir.

Map Local / Map Remote

Bu özellikler istekleri alternatif kaynaklara yönlendirir.

• Map Local: uzak sunucu yanıtının yerine yerel bir dosya sunar.

  1. Tools > Map Local... bölümüne gidin.
  2. Map Local'i etkinleştirin ve yeni bir girdi ekleyin.
  3. Eşlenecek uzak URL'nin Host ve Path değerlerini belirtin.
  4. Charles'ın sunması gereken dosyanın Local Path değerini seçin.
     Bu, frontend geliştirmede backend'i değiştirmeden UI değişikliklerini belirli sahte verilerle test etmek için kullanışlıdır.

• Map Remote: bir URL'den gelen isteği tamamen farklı bir URL'ye yönlendirir.

  1. Tools > Map Remote... bölümüne gidin.
  2. Map Remote'u etkinleştirin ve yeni bir girdi ekleyin.
  3. Özgün isteğin Host ve Path değerlerini belirtin.
  4. Yeni hedef URL'nin Host ve Path değerlerini belirtin.
     Bu, üretim API çağrılarını bir staging ortamına veya yerel bir geliştirme sunucusuna yönlendirmek için kullanışlıdır.

Throttling

Throttling, uygulamanın düşük ağ bağlantısı koşullarındaki performansını ve tepkiselliğini test etmek için çeşitli ağ koşullarını (örneğin çevirmeli bağlantı, 3G, özel hızlar) simüle eder.

1. Proxy > Throttle Settings... bölümüne gidin.
2. "Enable Throttling" seçeneğini işaretleyin.
3. Bir Preset seçin veya Bandwidth, Utilisation ve Latency değerlerini elle yapılandırın.
4. İsteğe bağlı olarak "Only for selected hosts" seçeneğini işaretleyin ve kısıtlanacak belirli host'ları ekleyin.

Repeat / Advanced Repeat

Bu işlevler istekleri yeniden göndermenizi sağlar.
* Repeat: Charles oturumundaki bir isteğe sağ tıklayıp "Repeat" seçerek onu bir kez yeniden gönderin.
* Advanced Repeat: bir isteğe sağ tıklayıp "Advanced Repeat" seçerek birden çok yineleme, eşzamanlılık ve gecikme yapılandırın; temel yük testi veya idempotency doğrulaması için kullanışlıdır.

Sık karşılaşılan senaryoların giderilmesi

| Sorun | Çözüm