Kebingungan karena Sulit Memahami Antarmuka IO Baru di Zig

• Pada Zig versi 0.15, diperkenalkan antarmuka IO baru (std.Io.Reader, std.Io.Writer)
• Tujuannya adalah memperbaiki kompleksitas metode IO lama dan masalah performa, tetapi justru menimbulkan kebingungan dalam penggunaan nyata
• Terkait penggunaan tls.Client dan buffer, ketidakkonsistenan cara pengiriman parameter makin menambah kebingungan
• Bahkan saat membuat contoh penggunaan dasar, ada tuntutan kompleks seperti menentukan berbagai ukuran buffer dan field opsi
• Karena kurangnya dokumentasi resmi, contoh kode, dan fungsi bantu, antarmuka ini tidak terasa intuitif bagi pemula

---

Antarmuka IO baru yang diperkenalkan di Zig 0.15 dan latar belakangnya

• Pada Zig 0.15, diperkenalkan tipe IO baru bernama std.Io.Reader dan std.Io.Writer
• Antarmuka IO sebelumnya menimbulkan kompleksitas karena masalah performa, pencampuran tipe, dan penggunaan anytype yang berlebihan
• Tujuan utama struktur IO baru ini adalah pemisahan tipe yang lebih jelas antar-antarmuka serta peningkatan performa

Masalah nyata saat menggunakan tls.Client dan antarmuka IO

• Saat memperbarui library SMTP lama, muncul kebingungan dalam cara menggunakan fungsi tls.Client.init
• Dalam dokumentasi, fungsi init disebut menerima pointer Reader dan Writer, serta satu set opsi sebagai argumen
• net.Stream di Zig masing-masing mengembalikan Stream.Reader/Stream.Writer melalui metode reader() dan writer()
  • Namun Stream.Reader/Stream.Writer tidak persis sama tipenya dengan std.Io.Reader/std.Io.Writer, sehingga perlu konversi
  • Untuk Reader harus memanggil metode interface(), sedangkan untuk Writer harus memakai field &interface, sehingga terasa kurang konsisten

Masalah pengaturan buffer dan field opsi

• stream.writer dan stream.reader masing-masing menerima buffer sebagai argumen
  • Buffer ditekankan sebagai elemen yang wajib dalam antarmuka IO baru
• Saat memanggil tls.Client.init, empat field opsi seperti ca_bundle, host, write_buffer, dan read_buffer wajib disediakan
  • Aturan pemisahan antara nilai yang dikirim lewat parameter opsi dan nilai yang diberikan langsung sebagai argumen terasa tidak jelas

var tls_client = try std.crypto.tls.Client.init(
  reader.interface(),
  &writer.interface,
  .{
    .ca = .{.bundle = bundle},
    .host = .{ .explicit = "www.openmymind.net"; } ,
    .read_buffer = &read_buf2,
    .write_buffer = &write_buf2,
  },
)

• Dalam praktiknya, jika pointer buffer tidak diberikan dengan benar, program bisa gagal berjalan sebagaimana mestinya atau mengalami hang, crash, dan berbagai masalah lain

Masalah keintuitifan saat menggunakan Reader

• Meskipun field reader pada tls.Client sendiri merupakan "stream yang sudah didekripsi", std.Io.Reader ternyata tidak memiliki metode read yang umum dipakai
• Sebagai gantinya, yang tersedia hanya metode yang kurang intuitif seperti peek, takeByteSigned, dan readSliceShort
• API yang paling mendekati penggunaan umum justru memakai metode stream untuk membaca data ke buffer

var buf: [1024]u8 = undefined;
var w: std.Io.Writer = .fixed(&buf);
const n = try tls_client.reader.stream(&w, .limited(buf.len));

Contoh kode lengkap dan masalah di dunia nyata

• Bahkan untuk membuat contoh minimum yang benar-benar berjalan, ada banyak hal yang harus diperhatikan seperti opsi, ukuran buffer, dan konversi tipe
• Karena minimnya test/dokumentasi/contoh, tingkat kesulitan belajar dan hambatan masuk menjadi tinggi
• Jika belum memahami konsistensi di dalam bahasa Zig atau underlying design-nya, ada banyak bagian yang terasa janggal
• Bahkan di dalam standard library sendiri, pola ini belum banyak digunakan sehingga referensi praktik nyata juga terbatas

Pengalaman dan kesimpulan

• Perubahan nama seperti std.fmt.printInt dan perubahan desain API membuat proses migrasi sendiri tidak mudah
• Berbagai kesulitan terus berulang, seperti pola reader.interface(), &writer.interface, cara pengiriman opsi, dan kebutuhan akan beberapa buffer sekaligus
• Dari sudut pandang orang yang belum terbiasa dengan protokol jaringan/keamanan seperti TLS, memahami persyaratan ini terasa lebih sulit lagi
• Secara keseluruhan, dibanding sebelumnya, masih ada banyak bagian yang belum memadai dari sisi kejelasan, dokumentasi, dan kemudahan penggunaan