تقدير المشروع
← كل المقالات

الخطوات الأولى مع ZIO، الجزء 1

تعرّف على ZIO – مكتبة Scala قوية تجعل بناء التطبيقات غير المتزامنة والمتزامنة (concurrent) أمراً سهلاً.

15 دقائق قراءة
ScalaApache KafkaZioالتبعيات

مرحباً! يفتتح هذا المنشور سلسلة مخصصة لـ ZIO – وهي مكتبة Scala قوية تسهّل تطوير التطبيقات غير المتزامنة والمتزامنة. على امتداد السلسلة سأوضح لك خطوة بخطوة كيفية استخدام اللبنات المختلفة لإطار ZIO لإنشاء تطبيق يعمل بالكامل، بحيث تخرج بفهم متين لما يستطيع ZIO فعله. سنعمل طوال السلسلة مع الإصدار 2 من ZIO.

وباستخدام هذا التطبيق مثالاً، سأوضح كيفية كتابة خدمات ZIO، وبناء مسارات بث (streaming) فعّالة، وتشغيل خادم HTTP مع web sockets، ومعالجة مشكلات التزامن (concurrency) باستخدام الذاكرة المعاملاتية البرمجية (STM) وبنى البيانات المناسبة، وضبط تطبيق ZIO وبالطبع اختباره.

ماذا سنبني؟

السياق

على الأرجح سمعت عن Kafka، أليس كذلك؟ إن لم يكن الأمر كذلك، فأقترح قراءة قدر يسير من المعلومات الأساسية قبل الخوض في هذه السلسلة. باختصار، هي منصة بث تتيح لك نشر (كتابة) الأحداث وتخزينها والاشتراك فيها (قراءتها).

في معماريات التطبيقات التي تستخدم Kafka، يكون عادةً مكوناً داخلياً يعيش داخل VPC ما ومخفياً عن العالم الخارجي. وهذا بالطبع هو الإعداد الذي نريده: فهو يمنع الوصول غير المصرّح به إلى وسطاء Kafka (Kafka Brokers) ويحمي بياناتنا من العمليات الضارة أو حتى العرضية. ومع ذلك، من السهل تخيّل حالة نرغب فيها في أن يتمكن العملاء من قراءة بعض البيانات.

لنفترض أننا نبني منصة يرفع إليها العملاء (أي الأنظمة الخارجية) بيانات. داخل المنصة نشغّل حسابات متنوعة غير متزامنة على تلك البيانات، فتنتج إشعارات تُحفظ في topics داخلية في Kafka خاصة بالمنصة. ولنقل إن علينا مشاركة هذه الإشعارات مع عملائنا، لأنهم يعتمدون على تلك المعلومات لبدء سير عملهم أو مواصلته. علينا تمرير الإشعارات المخزنة داخلياً في topics مغلقة داخل بنيتنا التحتية، ونريد فعل ذلك في الوقت الفعلي – أي أن كل إشعار جديد ينبغي أن يصل إلى العملاء المشتركين فوراً.

يتطلب هذا مكوناً وسيطاً (middleware)، وهذا بالضبط ما سنبنيه. الهدف بث الأحداث من topics داخلية وتمريرها إلى العملاء الخارجيين المشتركين. وتذكّر أن التطبيق، بما أنه ذو غرض تعليمي، يتضمن كثيراً من التبسيطات – لكن الشيفرة، فيما عدا ذلك، بمستوى الإنتاج.

نظرة عامة

قبل الغوص في استعراض النظام، لنحدد المتطلبات. سنفترض أن ما نريده أساساً هو السماح للعميل بـ “تتبّع” (tail) topics مختارة في Kafka. وبعبارة أخرى، لن يتلقى العميل الذي يلغي اشتراكه ثم يشترك مجدداً بعد 10 دقائق الرسائل التي نُشرت أثناء غيابه. هذا يبسّط التنفيذ ويبقي الشيفرة قصيرة ومباشرة نسبياً. سنسمي خدمتنا k-tail. والآن لنرسم هدفنا في مخطط بسيط.

نظرة عامة على k tail

سيشغّل التطبيق عمليتين أساسيتين: الأولى تستهلك الرسائل من Kafka، والثانية تمررها إلى العملاء المشتركين. لنستعرض المكونات المعنية، بدءاً من اليمين.

أولاً، نحتاج إلى نسخة مستهلك (consumer) تواصل قراءة الرسائل الجديدة من مجموعة topics مضبوطة مسبقاً. ثم تُحفظ هذه الرسائل مؤقتاً في مخزن (buffer). وبفضل المخزن يمكن معالجة استهلاك الرسائل وتمريرها بصورة مستقلة، ما يمنحنا مرونة من حيث السرعة ومعالجة الأخطاء. وأخيراً نحتاج إلى مكون مهمته تمرير الرسائل إلى العملاء. سنسميه broadcast.

وبمجموعها تشكل هذه المكونات خادم web socket يتيح للعملاء الاتصال والحصول على بيانات جديدة في الوقت الفعلي.

الخطة

تتألف سلسلة الخطوات الأولى مع ZIO من ثلاثة أجزاء، نستكشف فيها مفاهيم ZIO أثناء تنفيذ تطبيقنا.

يركّز الجزء الأول (المنشور الذي تقرؤه) على تنفيذ مكوّنَي المخزن والمستهلك؛ والهدف الرئيسي أن تعتاد أنواع ZIO وتتعلم كيفية إنشاء الخدمات والتعامل مع التبعيات.

يغطي الجزء الثاني تنفيذ مكوّنَي broadcast والخادم. سنعالج بعض تحديات التزامن بلبنات ZIO ونتعلم كيفية تشغيل خادم web socket.

أما الجزء الثالث فهو مخصص بالكامل للاختبار. سنستخدم مكتبة اختبار ZIO مع حاويات الاختبار (test containers).

التأثيرات (Effects)

إن كتبت شيفرة Scala من قبل، فمن المرجح أنك صادفت مصطلح effects. وعادةً توصف بأنها طريقة للتعامل مع الحسابات المتوازية أو التزامن أو عمليات الإدخال والإخراج (I/O) في تطبيقاتنا. يأتي الـ effect عادةً مع معامل نوع للمخرجات، مثل Future[String] أو IO[Int]، وقد يفشل، وقد يعتمد على موارد أو خدمات ليعمل.

وغالباً ما يتطلب معرفة هذه الخصائص الغوص في تفاصيل تنفيذ دوال أو قيم من هذه الأنواع وتحليلها. أما مع شيفرة ZIO المكتوبة جيداً، فقد يخبرنا توقيع النوع وحده أحياناً بكثير من المعلومات الأساسية عن effect معين.

في إطار ZIO يُعرَّف الـ effect بالصيغة ZIO[-R, +E, +A] بثلاثة معاملات نوع. قد يبدو هذا مربكاً في البداية، لكنه يتضح في ثانية أو ثانيتين أنه بسيط تماماً، فهو يمثل ZIO[Require, Error, Output]. يصف النوع حساباً يحتاج إلى أشياء من النوع R، وقد يفشل بخطأ من النوع E، أو قد ينتج مخرجاً ناجحاً من النوع A.

وعلى العكس، فإن الـ effect الذي لا متطلبات له نوعه ZIO[Any, _, _] ويمكنه العمل في “أي” ظروف. وبالمثل، فإن الـ effect المضمون ألا يفشل أبداً نوعه ZIO[_, Nothing, _].

يقيّم ZIO الـ effects بصورة كسولة، فإنشاء قيمة من النوع ZIO لا يشغّل الشيفرة الكامنة فوراً. ولتشغيل الـ effects وتنفيذ البرنامج علينا تهيئة مكوناتنا وإعداد بيئة التشغيل. يوفر ZIO ضمانات قوية في وقت الترجمة تساعدنا على هيكلة التبعيات وتنظيمها بشكل صحيح. وسنرى أمثلة على هذه الميزات لاحقاً.

تقدم المكتبة كثيراً من الأسماء البديلة (type aliases) للنوع ZIO. فمثلاً، الـ effect الذي لا متطلبات له ولا يمكن أن يفشل له الاسم البديل UIO[+A]، الذي يأخذ فقط معامل النوع الخاص بالمخرج الناجح. وسنستخدم الأسماء البديلة في شيفرة تطبيقنا كلما أمكن حتى تعتاد عليها.

الخدمات (Services)

بعد تقديم النوع ZIO، لننتقل إلى خدمتنا الأولى، Buffer. هناك بضع خطوات رئيسية وممارسات جيدة تستحق الاتباع عند كتابة الخدمات، وسأستعرضها أدناه. ولتوضيح المنطق أكثر، سأضيف أيضاً الأنواع الكاملة تعليقات في مقاطع الشيفرة على امتداد المنشورات.

تعريف Buffer

الخطوة الأولى هي إنشاء تعريف للخدمة. من الممارسات الجيدة – بل “القانون” – استخدام traits دائماً لهذا الغرض وعدم التعبير عن تبعيات الخدمة بوصفها متطلبات بيئة في التعريف نفسه. ماذا يعني هذا؟ إذا كان تنفيذنا لـ Buffer يعتمد على خدمة أخرى، فلا ينبغي أن تظهر هذه التبعية متطلباً في واجهة الخدمة. لنكتب تعريف الخدمة لـ Buffer.

trait Buffer {
  def offer(message: Message): UIO[Unit] // ZIO[Any, Nothing, Unit] 
  def poll(): UIO[Option[Message]] // ZIO[Any, Nothing, Option[Message]]
}

لا تحتاج offer ولا poll إلى أي شيء، وكلتاهما مضمونة الا تفشل، لذا لا نستخدم معاملَي النوع R (لا تبعيات في التعريف) وE ونعتمد على الأسماء البديلة لإبقاء الكتابة موجزة.

من المعتاد إعطاء الخدمة كائناً مرافقاً (companion object) فيه دوال وصول. نستخدم صيغاً من ZIO.service[T] لاسترجاع نسخ خدمة معينة من البيئة. هذا يعني أن على عملاء الـ buffer استدعاء الخدمة بـ ZIO.service[Buffer] ثم استدعاء offer مثلاً على تلك النسخة. يمكننا تسهيل ذلك بتعريف دوال وصول كما يلي.

object Buffer {
  def offer(message: Message): URIO[Buffer, Unit] =
    ZIO.serviceWithZIO[Buffer](_.offer(message))

  def poll(): URIO[Buffer, Option[Message]] =
    ZIO.serviceWithZIO[Buffer](_.poll())
}

يستطيع العملاء الآن الاستدعاء بصيغة أقصر، ببساطة Buffer.offer(...)، وسيحمل نوع الـ effect الناتج Buffer متطلب بيئة.

تنفيذ Buffer

بعد ذلك يأتي التنفيذ. لنفحص تنفيذ Buffer ونتحدث عن الممارسة الجيدة الثانية: ينبغي دائماً تمرير تبعيات الخدمة عبر مُنشئ الفئة.

final case class BufferImpl(queue: Queue[Message]) extends Buffer {
  override def offer(message: Message): UIO[Unit] =
    queue.offer(message).unit *> 
       ZIO.logInfo(s"buffer message ${message.id}")

  override def poll(): UIO[Option[Message]] = queue.poll
}

لهذا التنفيذ المحدد للـ buffer تبعية واحدة، مُعلنة في مُنشئ الفئة. ليس هناك الكثير لشرحه – ينبغي أن يبدو مألوفاً، فهو يتبع أسلوب OOP الكلاسيكي.

هذه التبعية الواحدة هي Queue من مكتبة ZIO – بنية بيانات غير متزامنة في الذاكرة، عملياتها لإضافة العناصر وسحبها غير حاجبة (non-blocking). نستخدم النسخة غير المحدودة من Queue، وسترى ذلك عند إنشاء Queue. تعمل الطابور مخزناً حتى يمكن معالجة الرسائل بطريقة مضبوطة. وهي تحافظ على ترتيب الرسائل (FIFO)، وهو أمر يهم عادةً عند التعامل مع Kafka.

بعد وضع الرسالة في الطابور، نسلسل تنفيذ effect آخر، مستخدمين ZIO.logInfo المفيدة للتسجيل (logging). ولربط هذين الـ effectين نستخدم المعامل *>، وهو صيغة من flatMap تتجاهل نتيجة الـ effect الذي يُطبَّق عليه.

مُنشئ Buffer

بعد جاهزية تعريف الخدمة وتنفيذها، يمكننا الانتقال إلى المُنشئ – الخطوة الأخيرة في إنشاء خدمات ZIO. لكن مهلاً: Buffer ليست سوى case class، ولها بالفعل مُنشئ فئة. هذا صحيح، لكن لأننا نريد الاستفادة من ميزات بيئة ZIO، سننشئ ما يسمى layers لخدماتنا. هكذا يتم ذلك.

object BufferImpl {
  // ZLayer[Any, Nothing, Buffer]
  val live: ULayer[Buffer] = 
     ZLayer(Queue.unbounded[Message].map(BufferImpl(_)))
}

تُعرَّف الـ layer عادةً في الكائن المرافق لفئة التنفيذ، ما يرفعها إلى ZLayer. ومرة أخرى يعبّر اسم بديل عن layer لا متطلبات إضافية لها (BufferImpl لا تعتمد على خدمة أخرى) ومضمون ألا تفشل عند إنشائها. تقبل الدالة ZLayer.apply() effect من النوع ZIO معاملاً، ما يجعلها مُنشئاً ذا تأثيرات (effectful). وبفضل هذا يمكننا تغطية الحالات التي تحتاج فيها الخدمة إلى موارد – كاتصال بقاعدة بيانات – قد يستغرق الحصول عليها وقتاً.

تتيح لنا الـ layers معالجة عمليات التهيئة هذه بكفاءة، وهو أمر يصعب تحقيقه بمُنشئات الفئات العادية. حتى المُنشئ Queue.unbounded هو effect، لأنه ينشئ طابوراً داخل بيئة تشغيل ZIO ويُرجع UIO[Queue[Message]]. وبتطبيق map عليه نحصل على نسخة من BufferImpl.

المستهلك (Consumer)

وبالطريقة نفسها، الخطوة الأولى كتابة تعريف خدمة لمكوّن مستهلك Kafka لدينا.

trait KTailConsumer {
  // ZStream[Any, Throwable, Message]
  val consume: Stream[Throwable, Message]
}

هنا يأتي دور ZStream، وهو مفهوم أساسي آخر في المكتبة.

يمكنك تخيّله خط أنابيب يسحب البيانات من مصدر ويحوّلها ويصدر بعض المخرجات. يمكن دمج الـ streams أو ترشيحها أو تحويلها بـ map أو اختزالها لإنجاز شتى المهام. وهي تصريحية (declarative) إلى حد كبير، فبمجرد أن تدرك أن عملية ما “بثية” بطبيعتها، يصبح نمذجتها بدلالات ZStream سهلاً.

استهلاك الرسائل من Kafka مثال رائع على حالة استخدام كهذه، لأنه يصف عملية تتلقى عناصر إدخال وتعالجها وتصدر بعض النتائج وتواصل ذلك إلى الأبد.

مثل ZIO وZLayer، لـ ZStream ثلاثة معاملات نوع، وتعني الشيء نفسه تماماً. يذكر تعريف المستهلك لدينا أنه يجب أن ينفذ stream قد يفشل بـ exception ويصدر قيماً من النوع Message. والقيمة consume ليست سوى وصف لخط أنابيب بث؛ وإنشاؤها لا يبدأ أي معالجة بعد.

في التنفيذ نستخدم zio-kafka – مكتبة من إطار ZIO تسهّل التكامل بين ZIO وKafka بتقديم تعريفات streams جاهزة ومعاملات شائعة. تجدر الإشارة إلى أن ZIO يوفر مجموعة واسعة من المكتبات لعمليات التطبيقات المعتادة، مثل الوصول إلى قواعد بيانات متنوعة والمقاييس ودعم JSON. يمكنك إيجاد القائمة الكاملة لإضافات المنظومة الرسمية وأدواتها هنا.

final case class KTailConsumerImpl(topics: Set[String], consumer: Consumer)
    extends KTailConsumer {
  override val consume: Stream[Throwable, Message] =
    consumer
      .plainStream[Any, Array[Byte], Array[Byte]](
        Topics(topics),
        Serde.byteArray,
        Serde.byteArray
      )
      .map(record =>
        Message(
          record.offset.topicPartition.topic(),
          record.partition,
          record.offset.offset,
          record.key,
          record.value
        )
      )
}

هذه المرة يعبّر نوع الـ layer عن تبعية محددة على خدمة KTailConfig، وهي خدمة الإعدادات في تطبيقنا. سنبنيها في الأجزاء التالية من السلسلة، حيث سنرى أيضاً كيف يسهّل ZIO ربط ملفات إعدادات التطبيق.

نعتمد على نسخة Consumer من مكتبة zio-kafka، التي توفر دالة اسمها plainStream. تُرجع هذه الدالة وصف ZStream لتدفق لا ينتهي من رسائل Kafka من topic معين، مع مفتاح وقيمة مُسلسَلين بالمُسلسِلات المحددة.

لمعالجة الرسائل نحوّلها بالعملية map، فنحوّل سجلات Kafka إلى كائنات Message من نطاق التطبيق. ولم يبق سوى تعريف layer لمستهلكنا.

object KTailConsumerImpl {
  // ZLayer[KTailConfig, Throwable, KTailConsumer]
  val live: RLayer[KTailConfig, KTailConsumer] =
    ZLayer.scoped {
      for {
        config <- ZIO.service[KTailConfig]
        topics = config.topics.toSet
        consumer <- Consumer.make(
          ConsumerSettings(config.bootstrapServers)
            .withGroupId(config.groupId)
        )
      } yield KTailConsumerImpl(topics, consumer)
    }
}

للوصول إلى خدمة معينة عبر بيئة ZIO نستدعي إحدى دوال ZIO.service[T]. ومن ثم تظهر هذه الخدمات باستمرار متطلبات في معاملات النوع (R) لـ effects وlayers لدينا. هنا نسترجع خدمة الإعدادات ونستخدم قيمها لبناء نسخة المستهلك الفعلية.

النطاق (Scope)

هل لاحظت أن المقطع أعلاه يستخدم مُنشئاً آخر، ZLayer.scoped؟ كلما ظهر النوع Scope في متطلبات effect ما، فهذا يعني أن الـ effect يصل إلى مورد يجب تنظيفه بشكل صحيح بعد ذلك. وبعبارة أخرى، يمثل Scope دورة حياة مورد.

هنا تبني layer الخاصة بـ KTailConsumerImpl نسخة Consumer عبر Consumer.make، التي تُرفق Scope مسؤولاً عن إغلاقه. وإذا تعمقنا في شيفرة zio-kafka فسنجد موضعاً يحتوي الشيفرة التالية (المبسطة).

ZIO.acquireRelease { 
    new KafkaConsumer[Array[Byte], Array[Byte]](...) 
} { consumer => consumer.close() }

تتيح لنا الدالة ZIO.acquireRelease إنشاء موارد ذات نطاق (scoped) وتطلب منا تقديم دالة استدعاء عكسي release يجري فيها التنظيف. ثم يُنشر معامل Scope متطلباً.

في الـ layer التي بنيناها لمستهلك k-tail، يكون تعبير for من النوع ZIO[Scope & KTailConfig, Throwable, KTailConsumerImpl]. ومع ذلك، وكما لاحظت، لا يظهر Scope بين متطلبات الـ layer. وهذا بفضل ZLayer.scoped.

فهي تزيل متطلب Scope وتربط عمر المورد المكتسب بعمر الـ layer نفسها. ونتيجة لذلك يُحرَّر المورد بمجرد انتهاء تشغيل أي سير عمل يعتمد على هذه الـ layer. في مثالنا يحدث ذلك عند إيقاف التطبيق.

تقدم أنواع ZIO الأخرى مُنشئات scoped أيضاً. تأمل ZStream.scoped، وتخيّل خط أنابيب يقرأ سجلات من قاعدة بيانات ويجري عليها بعض الحسابات. سنحتاج إلى مجمّع اتصالات (connection pool) بقاعدة البيانات ذي نطاق، لكن بمجرد بناء stream به، ترتبط دورة حياة المجمّع بالـ stream نفسه. وهذا منطقي، فينبغي أن يبقى مجمّع الاتصالات حياً ما دمنا نعالج سجلات من قاعدة البيانات.

من وجهة نظر المستخدم، هذه الآلية واضحة وبسيطة. فبيئة تشغيل ZIO تتولى كل العمل الشاق، وتضمن إغلاق المورد بسلاسة سواء نجح برنامجنا أم فشل أم تمت مقاطعته.

البرنامج

لنجمع الآن أول برنامج ZIO لدينا، وهو يستهلك الرسائل ويخزّنها مؤقتاً.

object Main extends ZIOAppDefault {

  private val program: RIO[Buffer & KTailConsumer, Unit] = for {
    consume <- KTailConsumer.consume
    _       <- consume.mapZIO(Buffer.offer).run(ZSink.drain)
  } yield ()

  override def run = program
}

تمتد نقطة دخول تطبيقنا من ZIOAppDefault، التي توفر إعداد تشغيل افتراضياً. علينا إعادة تعريف الدالة run وتوصيل منطق برنامجنا بها. يعرّف السطر الأول من البرنامج stream للمستهلك. بعد ذلك، باستخدام mapZIO، نضع كل رسالة من الـ stream في buffer. ولتحويل وصف الـ stream إلى effect قابل للتشغيل، علينا استدعاء إحدى صيغ run على النوع ZStream.

علينا أيضاً تحديد sink – الوجهة النهائية لمخرجات الـ stream. وبما أننا هنا لا نحتاج إلى فعل شيء بالنتائج، يمكننا استخدام ZSink.drain، التي تتجاهل المخرجات وتستنزف الـ stream حتى ينتهي. لكنه لن يُترجم بعد. لاحظ متطلب Buffer & KTailConsumer في نوع effect برنامجنا. فترجمة الشيفرة عند هذه النقطة تنتج خطأ كالتالي:

Your effect requires services that are not in the environment.
Please provide layers for the following 2 types:

    1. ktail.Buffer
    2. ktail.KTailConsumer

أفلا تكون الحياة أسهل بكثير لو كان كل خطأ وقت ترجمة بهذه الفائدة؟

لنتبع نصيحة المترجم ونوفر التبعيات لبرنامجنا.

override def run = program
  .provide(
    KTailConfig.live,
    BufferImpl.live,
    KTailConsumerImpl.live
  )

وبصورة بديهية جداً نستدعي الدالة provide من النوع ZIO لتمرير كل الخدمات المطلوبة بوصفها layers. تطبيقنا الآن جاهز للتشغيل.

الخلاصة

قدّم هذا المنشور الأول في السلسلة عدة مفاهيم أساسية في مكتبة ZIO. نظرنا في معنى معاملات النوع في أنواع Z، وكيفية كتابة الخدمات، وكيفية تركيب برامجنا وتوفير تبعياتها.

الأسئلة مرحب بها. شكراً!