ADITUS-Queue

غرفة الانتظار الافتراضية للمؤسسات

ADITUS-Queue غرفة انتظار افتراضية مستقلة تحمي أي موقع أو API أو خدمة عبر الإنترنت من ذروة الزيارات. تتكامل بسلاسة مع منصة ADITUS للتذاكر، ويمكن نشرها بصورة مستقلة أمام أي تطبيق ويب. ينتظر الزوار في غرفة مستضافة ويُسمح لهم بالدخول وفق ترتيب الوصول وبمعدل مضبوط لكل دقيقة. تتراوح خيارات التكامل من رابط Gateway واحد أو script tag من دون بنية تحتية لدى المشغّل، إلى فرض الحماية عبر reverse proxy أو CDN، وصولاً إلى REST API مباشرة.

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

على الرغم من العمق: الإعداد يستغرق دقائق، وليس أيامًا. رابط منشور واحد أو علامة نص برمجي واحدة - لا توجد بنية تحتية، ولا نشر، ولا تغييرات في التعليمات البرمجية من جانبك.

كيفية التكامل التحدث معنا

بداية سريعة: عش في أقل من دقيقتين

قم بحماية تطبيقك في أقل من دقيقتين: انسخ علامة البرنامج النصي في رأسك أو انشر رابط البوابة. لا توجد تغييرات على البنية التحتية للخادم الخاص بك. فقط عندما تريد أقصى قدر من التحكم، يمكنك تمكين الميزات الاختيارية المتقدمة - كل شيء آخر في هذه الصفحة هو بالضبط: عمق اختياري لوقت لاحق.

تقليديجامد ومحمّل فوق طاقته — يدخل جميع الزوار إلى المتجر في الوقت نفسه

ADITUS-Queueديناميكي ومحمي — دخول بالوتيرة الدقيقة التي يستطيع المتجر تحمّلها

1
إنشاء غرفة انتظار
في وحدة تحكم مسؤول ADITUS: الاسم وعنوان المتجر ومعدل القبول في الدقيقة. تغطي الإعدادات الافتراضية المعقولة كل شيء آخر.
2
انسخ سطرًا واحدًا
إما أن تنشر رابط البوابة الجاهزة بدلاً من رابط المتجر — أو تلصق علامة البرنامج النصي المعدة في صفحة المتجر، تمامًا مثل مقتطف التحليلات.
3
تم - قائمة الانتظار مسلحة
أقل من معدل القبول لا يرى الزوار غرفة الانتظار أبدًا. فقط عندما يحدث ارتفاع مفاجئ، يتم تدخل قائمة الانتظار - حيث نقوم باستضافتها وتوسيع نطاقها وتشغيلها.

ينمو معك: ثلاثة مستويات للحماية

إن قوة قائمة الانتظار هي مسار ترقية، وليست متطلبًا. يغطي المستوى 1 الغالبية العظمى من حالات الاستخدام بمفرده.

المستوى 1: الحماية القياسيةرابط البوابة أو علامة البرنامج النصي. جاهز على الفور، بدون بنية تحتية — يكفي لمعظم الحالات القياسية.جاهز للاستخدام الآن

المستوى 2: الحماية المتقدمةمعدل القبول ذاتي التنظيم من خلال فحص صحة المتجر - تقوم قائمة الانتظار بتشغيل الاتصال الهاتفي نيابةً عنك.خياري

المستوى 3: الحماية ضد الرصاصتقوية الحواف من خلال التحقق من JWT دون الاتصال بالإنترنت في Nginx أو Caddy أو CDN - لفرق DevOps.اختياري — لفرق DevOps

التكامل: خياران

أي خيار مناسب يعتمد على سؤال واحد: هل يمكن تغيير رابط المتجر المنشور؟ إذا كانت الإجابة بنعم، فإن رابط البوابة هو الخيار الأفضل - لا تصل حركة المرور إلى المتجر أبدًا قبل الدخول. إذا تم إصلاح عنوان URL للمتجر المنشور، فإن علامة البرنامج النصي تحمي المتجر دون أي تغيير في منشوره. بالإضافة إلى هذين الاثنين، يمكن فرض التحقق في الوكيل العكسي أو CDN (أدناه)، أو تشغيله مباشرة عبر REST API، أو التحقق منه في أي لغة خلفية باستخدام مكتبة JWT - Node.js، PHP، Java، .NET، Python، Go.

Gateway-LinkScript-Tagالوكيل العكسي/CDNREST-APIالتحقق من الخلفية (JWT، أي لغة)

الخيار أ: رابط البوابة (مستحسن)

توفر كل غرفة انتظار عنوان URL الخاص بها. يتم نشره في كل مكان قد يظهر فيه رابط المتجر - النشرة الإخبارية، والموقع الإلكتروني، ووسائل التواصل الاجتماعي. تأخذ قائمة الانتظار الطلب وتقرر جانب الخادم في خطوة واحدة: أقل من معدل القبول، تتم إعادة توجيه الزائر مباشرة إلى عنوان المتجر الذي تم تكوينه ولا يلاحظ قائمة الانتظار على الإطلاق؛ بمجرد تجاوز السعر، يصل الزائر إلى غرفة الانتظار ويتم إعادة توجيهه تلقائيًا عندما يحين دوره. لا يتلقى المتجر نفسه أي حركة مرور قبل القبول، حيث يتم استيعاب الطلبات قبل وصولها إلى البنية التحتية للمتجر.

newsletter.html

<!-- Der veröffentlichte Shop-Link zeigt auf die Queue statt auf den Shop: -->
<a href="https://developers.aditus.com/queue/<slug>/enter">Tickets kaufen</a>

بالنسبة لهذا الخيار، يجب تكوين العنوان المستهدف للمتجر (Ziel-URL) لقائمة الانتظار - وهو العنوان الذي يتم إعادة توجيه الزوار إليه. يصل الزائرون المقبولون إلى المتجر برمز دخول موقّع في عنوان URL - وهو HS256 JWT القياسي الذي يمكن للمتجر التحقق منه اختياريًا في وضع عدم الاتصال في الواجهة الخلفية الخاصة به باستخدام السر المشترك.تم توثيق الهيكل والمطالبات ومثال الواجهة الخلفية أدناه. ملحوظة: البوابة تحمي نقطة الدخول المنشورة؛ لا يزال بإمكان الزوار الذين يعرفون عنوان URL الخاص بالمتجر مباشرةً تجاوزه. إذا كان ذلك مهمًا، فادمج رابط البوابة مع علامة البرنامج النصي أو تحقق من الرمز المميز في الواجهة الخلفية للمتجر.

الخيار ب: علامة البرنامج النصي

عندما لا يمكن تغيير رابط المتجر المنشور، يكون التكامل عبارة عن علامة نصية واحدة. ويتم تسليمه مع صفحات المتجر - بنفس الطريقة التي يتم بها تسليم مقتطف التحليلات - ويجب أن يكون موجودًا في كل صفحة من المفترض أن تحميها غرفة الانتظار. يوصى بوضعه في <head> مع سمة التأجيل؛ الموقف الدقيق ليس حرجا.

shop.html

<!-- Auf jeder zu schützenden Shop-Seite im <head>: -->
<script src="https://developers.aditus.com/queue/<slug>/embed.js" defer></script>

تتوفر العلامة الدقيقة لغرفة انتظار معينة - مع إدخال العلامة الثابتة الصحيحة بالفعل - في وحدة تحكم مسؤول ADITUS لكل قائمة انتظار. يقوم البرنامج النصي بإجراء ثلاث عمليات فحص عند كل تحميل للصفحة:

1
الزائر يحمل تصريح مرور صالح
لا شيء يحدث. يتم تخزين المرور لكل جلسة متصفح؛ يستخدم الزائر المحل دون انقطاع.
2
يعود الزائر من غرفة الانتظار
يتم التحقق من رمز القبول في عنوان URL من جانب الخادم (التوقيع، تعيين قائمة الانتظار، انتهاء الصلاحية). إذا كان صالحًا، فسيتم تخزين تصريح الجلسة وإزالة الرمز المميز من شريط العناوين. الرموز غير الصالحة أو منتهية الصلاحية تعيد الزائر إلى غرفة الانتظار.
3
الزائر ليس لديه تصريح
إذا لم يكن هناك أحد ينتظر حاليًا، فسيتم قبول الزائر بصمت في الخلفية ويظل على الصفحة - ولن تظهر غرفة الانتظار أبدًا. فقط عندما يتم تجاوز معدل القبول المكوّن وتشكل قائمة انتظار، تتم إعادة توجيه الزائر إلى غرفة الانتظار؛ يتم تمرير الصفحة الحالية كعنوان URL تم التحقق من صحته، لذلك بعد القبول، يصل الزائر إلى الصفحة التي طلبها في الأصل بالضبط.

فشل مفتوح

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

لا يوجد إعادة توجيه مفتوحة

يتم التحقق من صحة عناوين URL المرتجعة من جانب الخادم مقابل المجالات التي تم تكوينها لقائمة الانتظار. تقوم غرفة الانتظار بالتوجيه فقط إلى صفحات المتجر المسجل.

التصلب: فرض القبول على وكيل الحافة

ترقية اختيارية – لفرق DevOpsغير مطلوب للإعداد أعلاه

كلا الخيارين أعلاه يحميان نقطة الدخول المنشورة. إذا كان لا بد من عدم إمكانية الوصول إلى المتجر دون السماح بالدخول حتى بالنسبة للزوار الذين يعرفون عنوان URL الخاص به مباشرة، فإن الشيك يتحرك أمام المتجر - إلى الوكيل العكسي أو CDN الذي ينهي حركة المرور الخاصة به. المنطق دائمًا هو نفس الخطوات الثلاث: خذ الرمز المميز من معلمة URL aditus_queue_token عندما يعود الزائر من غرفة الانتظار وقم بتخزينه كملف تعريف ارتباط؛ في كل طلب، تحقق من الرمز المميز من ملف تعريف الارتباط باعتباره HS256 JWT القياسي مع السر المشترك (قائمة انتظار aditus للمصدر، جمهور قائمة الانتظار، انتهاء الصلاحية)؛ بدون رمز صالح، قم بإعادة التوجيه إلى غرفة الانتظار على https://developers.aditus.com/queue/<slug>. التحقق غير متصل بالإنترنت - لا يتصل الوكيل مطلقًا بقائمة الانتظار ولا يضيف أي وقت استجابة. توضح الرسومات التالية نمط أربع بيئات مشتركة؛ تكييفها مع الإعداد الخاص بك.

Nginxوحدة njs - التحقق مباشرة في الوكيل، لا توجد خدمة إضافية.مقتطف متضمن

Caddyjwtauth plugin — تكوين خالص، وليس سطرًا واحدًا من التعليمات البرمجية.مقتطف متضمن

Cloudflareالعامل على الحافة – يتم فرضه في جميع أنحاء العالم قبل وصول حركة المرور إلى المتجر.مقتطف متضمن

AWS CloudFrontLambda@Edge — يتم إجراء الفحص في شبكة AWS العالمية.مقتطف متضمن

معيار HS256 JWTالتحقق دون الاتصال بالإنترنت - لا يوجد رد اتصالصفر أضاف الكمونيعمل مع أي وكيل عكسي

Nginx (njs)

# Skizze: Nginx mit njs (js_import) — prüft den Zugriffs-Token als HS256-JWT
# direkt am Proxy, ohne Rückruf an die Queue. An die eigene Umgebung anpassen.

# nginx.conf:
#   env ADITUS_QUEUE_SECRET;
#   js_import queue from /etc/nginx/queue.js;
#   server {
#     location /       { js_content queue.gate; }
#     location @shop   { proxy_pass http://shop_backend; }
#   }

// /etc/nginx/queue.js:
const crypto = require('crypto');
const SLUG = '<slug>';
const SECRET = process.env.ADITUS_QUEUE_SECRET; // Shared Secret der Queue

function claims(token) {
  const p = token.split('.');
  if (p.length !== 3) return null;
  const sig = crypto.createHmac('sha256', SECRET)
    .update(p[0] + '.' + p[1]).digest('base64url');
  if (sig !== p[2]) return null;
  const c = JSON.parse(Buffer.from(p[1], 'base64url'));
  const ok = c.iss === 'aditus-queue' && c.aud === SLUG && c.exp > Date.now() / 1000;
  return ok ? c : null;
}

function gate(r) {
  const fromUrl = r.args.aditus_queue_token;
  const m = (r.headersIn.Cookie || '').match(/(?:^|;\s*)aditus_queue=([^;]+)/);
  const token = fromUrl || (m && m[1]);
  if (!token || !claims(token)) {
    // Kein gültiger Token -> zurück in den Warteraum
    r.return(302, 'https://developers.aditus.com/queue/' + SLUG);
    return;
  }
  if (fromUrl) {
    // Token aus der Rücksprung-URL in ein Sitzungs-Cookie übernehmen
    r.headersOut['Set-Cookie'] =
      'aditus_queue=' + fromUrl + '; Path=/; Secure; HttpOnly; Max-Age=600';
  }
  r.internalRedirect('@shop');
}

export default { gate };

Caddyfile

# Skizze: Caddy mit dem jwtauth-Plugin (github.com/ggicci/caddy-jwt).
# Token kommt beim Rücksprung als ?aditus_queue_token=… oder danach als Cookie;
# jwtauth prüft beide Quellen. An die eigene Umgebung anpassen.
shop.example.com {
  route {
    jwtauth {
      sign_key {env.ADITUS_QUEUE_SECRET}
      sign_alg HS256
      from_query aditus_queue_token
      from_cookies aditus_queue
      issuer_whitelist aditus-queue
      audience_whitelist <slug>
      user_claims qnr
    }
    # Token aus der URL einmalig in ein Cookie übernehmen
    @rueckkehr query aditus_queue_token=*
    header @rueckkehr Set-Cookie "aditus_queue={http.request.uri.query.aditus_queue_token}; Path=/; Secure; HttpOnly; Max-Age=600"
    reverse_proxy shop_backend:8080
  }
  # Ohne gültigen Token: zurück in den Warteraum
  handle_errors {
    @unauth expression {http.error.status_code} == 401
    redir @unauth https://developers.aditus.com/queue/<slug> 302
  }
}

Cloudflare Worker

// Skizze: Cloudflare Worker vor dem Shop — prüft den HS256-JWT offline per
// WebCrypto. Secret als Worker-Secret ADITUS_QUEUE_SECRET hinterlegen.
const SLUG = "<slug>";
const ROOM = "https://developers.aditus.com/queue/" + SLUG;

export default {
  async fetch(req, env) {
    const url = new URL(req.url);
    const fromUrl = url.searchParams.get("aditus_queue_token");
    const m = (req.headers.get("Cookie") || "").match(/(?:^|;\s*)aditus_queue=([^;]+)/);
    const token = fromUrl || (m && m[1]);
    if (!token || !(await valid(token, env.ADITUS_QUEUE_SECRET))) {
      return Response.redirect(ROOM, 302); // zurück in den Warteraum
    }
    if (fromUrl) {
      // Token in ein Cookie übernehmen und die URL bereinigen
      url.searchParams.delete("aditus_queue_token");
      return new Response(null, {
        status: 302,
        headers: {
          Location: url.toString(),
          "Set-Cookie": "aditus_queue=" + token +
            "; Path=/; Secure; HttpOnly; Max-Age=600",
        },
      });
    }
    return fetch(req); // gültiger Pass -> durch zum Shop
  },
};

async function valid(token, secret) {
  const p = token.split(".");
  if (p.length !== 3) return false;
  const key = await crypto.subtle.importKey(
    "raw", new TextEncoder().encode(secret),
    { name: "HMAC", hash: "SHA-256" }, false, ["verify"],
  );
  const ok = await crypto.subtle.verify(
    "HMAC", key, b64url(p[2]),
    new TextEncoder().encode(p[0] + "." + p[1]),
  );
  if (!ok) return false;
  const c = JSON.parse(new TextDecoder().decode(b64url(p[1])));
  return c.iss === "aditus-queue" && c.aud === SLUG && c.exp > Date.now() / 1000;
}

function b64url(v) {
  return Uint8Array.from(
    atob(v.replace(/-/g, "+").replace(/_/g, "/")),
    (ch) => ch.charCodeAt(0),
  );
}

AWS CloudFront (Lambda@Edge)

// Skizze: AWS CloudFront mit Lambda@Edge (Viewer-Request, Node.js).
// Gleiches Muster: Token aus ?aditus_queue_token oder Cookie, HS256 offline
// prüfen, ohne gültigen Token in den Warteraum umleiten.
// Hinweis: Lambda@Edge hat keine Umgebungsvariablen — das Secret z. B. beim
// Deployment einbetten oder aus SSM/Secrets Manager cachen.
'use strict';
const crypto = require('crypto');
const SLUG = '<slug>';
const ROOM = 'https://developers.aditus.com/queue/' + SLUG;
const SECRET = '<ADITUS_QUEUE_SECRET>';

exports.handler = async (event) => {
  const req = event.Records[0].cf.request;
  const qs = new URLSearchParams(req.querystring || '');
  const fromUrl = qs.get('aditus_queue_token');
  const cookie = (req.headers.cookie || []).map((h) => h.value).join('; ');
  const m = cookie.match(/(?:^|;\s*)aditus_queue=([^;]+)/);
  const token = fromUrl || (m && m[1]);

  if (!token || !valid(token)) {
    return redirect(ROOM); // zurück in den Warteraum
  }
  if (fromUrl) {
    // Token in ein Cookie übernehmen und die URL bereinigen
    qs.delete('aditus_queue_token');
    const clean = req.uri + (qs.toString() ? '?' + qs.toString() : '');
    return redirect(clean, {
      'set-cookie': [{ key: 'Set-Cookie', value:
        'aditus_queue=' + token + '; Path=/; Secure; HttpOnly; Max-Age=600' }],
    });
  }
  return req; // gültiger Pass -> durch zum Shop (Origin)
};

function valid(token) {
  const p = token.split('.');
  if (p.length !== 3) return false;
  const sig = crypto.createHmac('sha256', SECRET)
    .update(p[0] + '.' + p[1]).digest();
  const got = Buffer.from(p[2], 'base64url');
  if (got.length !== sig.length || !crypto.timingSafeEqual(sig, got)) {
    return false;
  }
  const c = JSON.parse(Buffer.from(p[1], 'base64url'));
  return c.iss === 'aditus-queue' && c.aud === SLUG && c.exp > Date.now() / 1000;
}

function redirect(location, extraHeaders) {
  return {
    status: '302',
    headers: Object.assign(
      { location: [{ key: 'Location', value: location }] },
      extraHeaders || {},
    ),
  };
}

ملحوظة: مع تطبيق تطبيق الحافة، يحتاج كل زائر إلى رمز مميز - بما في ذلك أولئك الذين قد يمرون بصمت دون معدل القبول. انشر رابط البوابة (الخيار أ) بجانبه، أو اسمح للوكيل بإعادة توجيه الزائرين بدون رموز إلى غرفة الانتظار، التي تصدر رمزًا مميزًا على الفور بينما لا ينتظر أحد.

الإعداد: ما يحتاجه ADITUS منك

تم تكوين غرفة الانتظار بواسطة ADITUS. بالنسبة للإعداد، قم بتوفير ما يلي:

الرسم (اختياري)

صورة رأسية لصفحة غرفة الانتظار، على سبيل المثال: مفتاح الحدث مرئي. تنسيق أفقي، على الأقل 920 × 380 بكسل (يتم عرضه بعرض يصل إلى 460 بكسل، ويتم اقتصاصه إلى أقصى ارتفاع يبلغ 190 بكسل)، أو JPG أو PNG، ويتم تسليمه كعنوان URL HTTPS يمكن الوصول إليه بشكل عام أو كملف إلى ADITUS.

النص (اختياري)

رسالة قصيرة تظهر أسفل عنوان غرفة الانتظار، على سبيل المثال: ملاحظة حول البيع أو الانتظار المتوقع. نص عادي، يتم الاحتفاظ بفواصل الأسطر؛ الطول الموصى به يصل إلى حوالي 300 حرف. يتم عرض النص تمامًا كما هو مقدم — إذا كنت تخدم زوارًا دوليين، فقم بتقديمه باللغة المناسبة أو ثنائي اللغة.

لون التمييز (اختياري)

لون العلامة التجارية كقيمة سداسية عشرية (على سبيل المثال #0a63c9). يقوم بتلوين شريط التقدم والمؤشر المباشر على صفحة غرفة الانتظار؛ بدون قيمة، يتم استخدام اللون الافتراضي لـ ADITUS. إلى جانب الرسم والنص، تعتمد غرفة الانتظار العلامة التجارية للمنظم.

مجالات المتجر

نطاقات الصفحات التي سيتم تشغيل البرنامج النصي عليها (على سبيل المثال، shop.example.com). وهي تحدد عناوين URL التي تقبلها غرفة الانتظار.

اسم العرض، عنوان URL المستهدف، المعدل

عنوان غرفة الانتظار (على سبيل المثال، اسم الحدث)، وعنوان URL المستهدف للزوار المقبولين (المطلوب لرابط البوابة - وهو عنوان المتجر الذي تقوم البوابة بإعادة التوجيه إليه)، ومعدل القبول بالزائرين في الدقيقة. المعدل هو عتبة الإنتاجية: طالما يصل عدد أقل من الزوار عما يسمح به المعدل، يمر الجميع دون غرفة انتظار. ويمكن تعديله في أي وقت أثناء تشغيل قائمة الانتظار.

التحديثات تلقائيا (كل بضع ثوان)

رقم الإنتظار - يتم تعيينه مرة واحدة عند فتح الصفحة والاحتفاظ بها طوال فترة الانتظار، حتى أثناء إعادة التحميل.

الوظيفة والرقم المقبول - كم عدد الأرقام المقبلة وما هو الرقم الذي يتم قبوله حاليًا. العدد المقبول ينمو بشكل مستمر مع معدل القبول.

شريط التقدم — يتصور مدى تقدم القبول نحو رقم الزائر.

الانتظار المقدر - محسوبة من الوضع الحالي ومعدل القبول؛ فإنه يقصر مع تقدم القبول. بمجرد قبول رقم الزائر، تقوم الصفحة بإعادة التوجيه إلى المتجر تلقائيًا - دون الحاجة إلى أي تفاعل.

تم تكوينه مرة واحدة (ثابت)

صورة الرأس - اختياري، على سبيل المثال. مفتاح الحدث مرئي.

اسم العرض - عنوان غرفة الانتظار، على سبيل المثال. اسم الحدث.

رسالة — نص اختياري أسفل العنوان، يظهر تمامًا كما هو منصوص عليه.

رسم تخطيطي لصفحة غرفة الانتظار: العلامات المرجانية هي قيم حية يتم تحديثها تلقائيًا، ويتم تكوين العلامات الرمادية مرة واحدة.

صفحة غرفة الانتظار المستضافة: صورة الرأس ورقم الانتظار والموقع والانتظار المقدر — غرفة الانتظار المستضافة مع صورة رأسية ورسالة: رقم الانتظار والموقع والرقم المقبول وتحديث الانتظار المقدر تلقائيًا.

صفحة غرفة الانتظار نفسها ثنائية اللغة (الألمانية/الإنجليزية). يتم اختيار اللغة تلقائيًا من إعدادات متصفح الزائر؛ لا يوجد تكوين مطلوب.

العمليات: لوحة القيادة الحية

أثناء البيع، تراقب ADITUS كل غرفة انتظار في لوحة معلومات حية: تُظهر المقاييس عدد الانتظار الحالي، وتدفق الزوار الجدد مقابل معدل القبول، ومعدل القبول نفسه (مع السقف الذي تم تكوينه عندما يكون معدل التنظيم الذاتي قيد التشغيل) والانتظار المقدر للوافدين الجدد. يتتبع المخطط المكون من سلسلتين عدد الانتظار مقابل التدفق الوارد بمرور الوقت، وتقوم مثيلات قائمة الانتظار التي تخدم حركة المرور بالإبلاغ عن الحمل الخاص بها - وحدة المعالجة المركزية والذاكرة ومعدل الطلب. يمكن تعديل معدل القبول في أي لحظة أثناء تشغيل قائمة الانتظار - على سبيل المثال عندما يظهر المتجر مساحة للرأس.

لوحة المعلومات المباشرة في وحدة تحكم مسؤول ADITUS: مقاييس لعدد الانتظار والتدفق ومعدل القبول والانتظار المقدر ومخطط تاريخي من سلسلتين ومثيلات قائمة الانتظار المبلغ عنها ذاتيًا — لوحة المعلومات المباشرة في وحدة تحكم المشرف ADITUS، يتم تحديثها كل 3 ثوانٍ أثناء البيع.

العمليات: اختبارات الحمل والفحص الصحي

لا يُقال إن قائمة الانتظار مقاومة للتحميل فحسب، بل يتم اختبارها بانتظام. من وحدة تحكم مسؤول ADITUS، تطلق اختبارات التحميل طلبات حقيقية في غرفة انتظار اختبار مخصصة في نظام الإنتاج (لا يتم لمس غرف الانتظار الإنتاجية مطلقًا). يحاكي الاختبار مسار الزائر — الانضمام واستقصاء الحالة — بمعدل ومدة قابلة للتكوين. تُظهر المقاييس المباشرة معدل الطلب الذي تم تحقيقه والمتوسط ووقت الاستجابة p95 ومعدل الخطأ؛ يقوم مخطط لكل ثانية بتتبع الإنتاجية مقابل زمن الاستجابة، ويتم الاحتفاظ بكل تشغيل في سجل بحيث تظل النتائج قابلة للمقارنة بمرور الوقت. يتم تشغيل الاختبارات أيضًا وفقًا لجدول زمني متكرر، ويتم وضع علامة تلقائيًا على التشغيل المجدول الذي يؤدي أداءً أسوأ بشكل واضح من عمليات التشغيل السابقة المماثلة.

اختبار حمل قيد التشغيل في وحدة تحكم مسؤول ADITUS: مقاييس للمعدل الذي تم تحقيقه، وزمن الوصول p50/p95 ومعدل الخطأ، ومخطط لكل ثانية، ومثيلات قائمة الانتظار المبلغ عنها ذاتيًا، وسجل التشغيل — اختبار التحميل مقابل قائمة انتظار الإنتاج: مؤشرات الأداء الرئيسية المباشرة، والمخطط لكل ثانية، ومثيلات قائمة الانتظار النشطة أثناء الاختبار، وتاريخ عمليات التشغيل السابقة.

بالنسبة للمراقبة الخارجية، تعرض خدمة قائمة الانتظار فحص الصحة العامة على /queue/healthz. فهو يجيب دون مصادقة ودون لمس قاعدة البيانات - وهي إشارة توفر بسيطة لمراقبة وقت التشغيل. أثناء اختبار التحميل، تعرض وحدة تحكم المشرف بالإضافة إلى ذلك مثيلات قائمة الانتظار التي تم الإبلاغ عنها ذاتيًا مع وحدة المعالجة المركزية والذاكرة وتأخر حلقة الأحداث ومعدل الطلب؛ تحت التحميل، يبدأ النظام الأساسي مثيلات إضافية تلقائيًا، ويجعل الاختبار ذلك مرئيًا.

العمليات: معدل القبول ذاتي التنظيم

ترقية اختيارية — السعر الثابت يعمل بشكل جيد

معدل القبول هو المؤشر الوحيد الذي يقرر كل شيء خلال فترة البيع - وحتى الآن، كان على شخص ما أن يراقبه. لم يعد الأمر كذلك: يمكن لقائمة الانتظار تنظيم السعر نفسه، مدفوعًا بالحالة الفعلية للمتجر المحمي. والنتيجة هي غرفة انتظار يتم بيعها بالسرعة التي يمكن للمتجر التعامل معها بأمان - في كل لحظة، دون أن يلمس أي شخص القرص.

الإنتاجية الكاملة، صفر المخاطر

في حين أن المتجر في حالة جيدة، فإن السعر يرتفع بخطوات صغيرة ويتحول الإرتفاع غير المستغل إلى مبيعات. في اللحظة التي يظهر فيها المتجر ضغطًا، ينخفض المعدل بشكل حاد - بشكل غير متماثل بشكل متعمد: الإغاثة فورية، والحمل يعود بعناية.

آمنة من الفشل حسب التصميم

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

القواعد الخاصة بك، شفافة تماما

أنت تحدد ما تعنيه كلمة "صحي" - وقت الاستجابة، وحمل وحدة المعالجة المركزية، وأي مقياس يقدمه متجرك. يتم تسجيل كل تعديل تلقائي وإظهاره في لوحة المعلومات المباشرة، مع القاعدة التي أدت إلى تشغيله.

بدلاً من تعديل معدل القبول يدويًا، يمكن لغرفة الانتظار تنظيمه تلقائيًا من خلال الفحص الصحي للمتجر المحمي. يقوم ADITUS باستقصاء عنوان URL الخاص بالمتجر على فترات زمنية قابلة للتكوين وتقييم وقت الاستجابة، واختياريًا، الحقول الرقمية من استجابة JSON مقابل القواعد المحددة من قبل المشغل (على سبيل المثال: وقت الاستجابة أقل من 500 مللي ثانية، وتحميل وحدة المعالجة المركزية أقل من 0.8). في حين أن المتجر في حالة جيدة، يتم رفع السعر ببطء في خطوات صغيرة؛ بمجرد انتهاك القاعدة، يتم تخفيضها بسرعة بنسبة مئوية - بشكل غير متماثل عمدًا، لذلك يتم تخفيف المتجر على الفور ولكن يعود التحميل بحذر. يبقى المعدل دائمًا ضمن الحد الأدنى والحد الأقصى المحددين.

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

تظل نقطة النهاية الصحية على جانب المتجر تافهة: عنوان URL HTTPS، يمكن الوصول إليه دون مصادقة، والإجابة على 2xx. يعد نص JSON اختياريًا - أي حقول رقمية (يتم تسطيح الكائنات المتداخلة إلى مسارات نقطية) تصبح مقاييس يمكن للقواعد الرجوع إليها:

مثال على الاستجابة الصحية للمتجر

{
  "status": "ok",
  "responseBudgetMs": 500,
  "metrics": {
    "cpuLoad": 0.42,
    "dbPoolWaiting": 0,
    "openCheckouts": 118
  }
}

// Nutzbare Messwerte (Punktpfade):
//   responseBudgetMs, metrics.cpuLoad, metrics.dbPoolWaiting, metrics.openCheckouts
// Dazu immer verfügbar: die gemessene Antwortzeit (ms).

العمليات: حماية الروبوتات لإثبات العمل

بالنسبة لمبيعات الطلب المرتفع، يمكن أن تطلب غرفة الانتظار أيضًا إثباتًا للعمل قبل إصدار رقم الانتظار. يقوم المتصفح بعد ذلك بحل لغز تشفير صغير في الخلفية - غير مرئي للزائر، وفي مستوى الصعوبة الافتراضي، لا يستغرق الأمر سوى أقل من ثانية على الأجهزة العادية. بالنسبة لمزرعة الروبوتات، تتغير الصورة: كل عملية ربط تكلف نفس العمل الحسابي، وبالتالي فإن رسم آلاف الأرقام يصبح مكلفًا نسبيًا بدلاً من أن يكون مجانيًا. يتم إيقاف الحماية بشكل افتراضي ويتم تمكينها لكل غرفة انتظار في وحدة تحكم المشرف الخاصة بـ ADITUS؛ الصعوبة قابلة للتعديل (8 إلى 24 بت، الافتراضي 15 — كل بت إضافي يضاعف العمل). تتعامل صفحة غرفة الانتظار المستضافة مع اللغز تلقائيًا؛ لا شيء يتغير بالنسبة لتكامل المتجر.

إحدى النتائج المتعمدة: أثناء تنشيط الحماية، يتم تعطيل المرور الصامت تحت معدل القبول - يمر كل زائر عبر غرفة الانتظار، لأنه هناك فقط يتم إجراء إثبات العمل. وملاحظة على النطاق: إثبات العمل يحمي إصدار أرقام الانتظار من الانضمام الجماعي. إنه بمثابة لبنة أساسية ضد المشترين الآليين، وليس دفاعًا كاملاً عن الروبوتات - قم بدمجه مع التدابير الموجودة في المتجر نفسه (مثل حدود الشراء) عند الحاجة.

فقط عمليات التكامل المخصصة التي تستدعي واجهة برمجة تطبيقات قائمة الانتظار هي التي تحتاج إلى حل اللغز بنفسها. التدفق: جلب التحدي، والعثور على الرقم الذي يبدأ تجزئة التحدي SHA-256 بالإضافة إلى الرقم بالعدد المطلوب من البتات الصفرية، وإرسال كليهما مع طلب الانضمام. التحديات موقعة وصالحة لمدة خمس دقائق؛ بالإضافة إلى ذلك، يتم منع إعادة الاستخدام لكل مثيل: (API)

تدفق إثبات العمل لعمليات التكامل المخصصة

// 1. Challenge holen (nur relevant, wenn PoW für die Queue aktiv ist)
GET https://developers.aditus.com/queue/<slug>/pow
// -> { queue, enabled: true, challenge, bits, expiresInSeconds: 300,
//      algorithm: "sha256" }

// 2. Nonce suchen: SHA-256(challenge + "." + nonce) muss mit <bits>
//    Null-Bits beginnen. Im Browser per WebCrypto — bei der
//    Standard-Schwierigkeit deutlich unter einer Sekunde.

// 3. Beitritt mit Lösung
POST https://developers.aditus.com/queue/<slug>/join
{ "pow": { "challenge": "…", "nonce": "…" } }

// Ohne oder mit ungültiger Lösung antwortet /join mit
// 428 Precondition Required — und liefert im Fehlerkörper direkt eine
// frische Challenge mit, sodass kein zweiter Abruf nötig ist.

العمليات: الافتتاحيات المقررة مع قرعة عادلة

بالنسبة للمبيعات المعلن عنها، يمكن تحديد وقت محدد لفتح غرفة الانتظار. الزائرون الذين يصلون مبكرًا يهبطون في طابور مسبق: تعرض صفحة غرفة الانتظار العد التنازلي للافتتاح، ولم يتم قبول أي شخص حتى الآن. في وقت الافتتاح، تحدث الخطوة الحاسمة - حيث يتم رسم أمر القبول بين جميع المنتظرين بحلول ذلك الوقت بشكل عشوائي إلى حد ما. وبالتالي، فإن الوصول مبكرًا بثلاث ساعات ليس له أي ميزة مقارنة بالوصول مبكرًا بثلاث دقائق؛ تفقد الماراثونات المحدثة وعلامات تبويب المتصفح المعسكرة وجهة نظرها. كل من ينضم بعد الافتتاح يتم وضعه خلف المجموعة المرسومة بترتيب الوصول الطبيعي.

السحب عبارة عن تبديل رياضي على أرقام الانتظار الصادرة قبل الافتتاح - يحصل كل رقم على موضع واحد بالضبط، ولا يضيع أي منها، ولا يظهر أي منها مرتين، ولا يمكن التنبؤ بالمهمة من ترتيب الانضمام. يؤدي تغيير وقت الفتح في وحدة تحكم المشرف إلى إعادة تفعيل السحب؛ لم يتغير شيء بالنسبة لتكامل المتجر أو واجهة برمجة التطبيقات. (API)

العمليات: التخلي عن الكشف

ليس كل من يرسم رقم انتظار يبقى. عادةً ما تترك علامات التبويب المغلقة والمتصفحات المهجورة فجوات: تتحرك نافذة القبول فوق الأرقام التي لم تعد مملوكة لأي شخص، وتنخفض الإنتاجية الحقيقية إلى ما دون المعدل الذي تم تكوينه. مع تمكين اكتشاف التخلي، تقوم صفحة غرفة الانتظار المستضافة بالإبلاغ عن وجودها بشكل منتظم. إذا ظل الرقم صامتًا لفترة أطول من فترة السماح التي تم تكوينها (60 إلى 3600 ثانية، الافتراضية 180)، فسيتم اعتباره مهجورًا - وتتقدم نافذة القبول بهذا المقدار بشكل أسرع، لذلك تذهب الخانات الفارغة إلى الزائرين الذين ما زالوا ينتظرون بالفعل.

يكون الاكتشاف متسامحًا بشكل متعمد: يتم قبول الزائر العائد الذي تم احتساب رقمه على أنه مهجور ولكنه موجود بالفعل ضمن نافذة القبول بشكل طبيعي - تتسارع نبضات القلب فقط، ولا تلغي القبول أبدًا. ترسل عمليات التكامل المخصصة التي تنشئ صفحة انتظار خاصة بها نفس الإشارة عبر POST /queue/<slug>/heartbeat (نص JSON مع رقم الانتظار، يوصى به كل 60 ثانية).

العمليات: رموز تجاوز VIP

الصحافة والشركاء ووحدات نادي المعجبين: يجب ألا يرى بعض الزوار أبدًا غرفة انتظار. بالنسبة لهم، يمكن إنشاء رموز التجاوز لكل غرفة انتظار في وحدة تحكم المشرف الخاصة بـ ADITUS - كل منها مزود بملصق وحد استخدام اختياري وتاريخ انتهاء صلاحية اختياري، ويمكن تعطيل كل منها أو حذفها في أي وقت. تتم مشاركة الرمز كرابط بسيط: /queue/<slug>/enter?code=… يعيد التوجيه مباشرة إلى المتجر باستخدام رمز دخول صالح، بعد قائمة الانتظار بأكملها. يمكن لعمليات التكامل المخصصة استرداد الرموز عبر POST /queue/<slug>/bypass بدلاً من ذلك واستلام الرمز المميز كـ JSON.

خاصيتان أمنيتان متعمدتان: رمز غير صالح عند رابط البوابة يمر بصمت إلى المسار العادي - لا يستطيع الغرباء معرفة ما إذا كان الرمز موجودًا أم لا. ويجيب مسار JSON بشكل مماثل على الرموز غير الصالحة، ومنتهية الصلاحية، والمستنفدة، والمعطلة، لذلك لا يوجد أوراكل لتخمين الرموز. يتم وضع علامة على عمليات القبول التجاوزية على هذا النحو في الرمز المميز ولا تستهلك فتحات القبول العادية.

التفاصيل الفنية

الأقسام التالية غير مطلوبة للتكامل — علامة البرنامج النصي أعلاه مكتملة. إنهم يوثقون كيفية عمل النظام أدناه للتقييم الفني وللمحلات التجارية التي ترغب في التحقق من القبول في الواجهة الخلفية الخاصة بها.

كيف يعمل القبول

يتم إصدار رقم انتظار تسلسلي لكل زائر من خلال زيادة قاعدة بيانات ذرية واحدة. القبول يتقدم بشكل مستمر: يتم حساب الرقم المقبول حاليًا على أنه الأساس + المعدل × الدقائق المنقضية. استقصاء الحالة للقراءة فقط ولا يمس قاعدة البيانات لكل طلب. لا توجد حالة لكل زائر على الخادم، ولا توجد مهمة cron ولا مؤقت - لا يمكن أن تصبح خدمة قائمة الانتظار نفسها عنق الزجاجة تحت التحميل. يؤدي إيقاف قائمة الانتظار مؤقتًا إلى إيقاف القبول وإصدار أرقام جديدة؛ تسري تغييرات الأسعار بشكل مستمر ولا يتناقص العدد المقبول أبدًا.

الإنصاف: من يأتي أولاً يخدم أولاً

يتم القبول بشكل صارم على أساس أسبقية الحضور (FCFS): تعمل الزيادة الذرية على إصلاح موضع كل زائر في لحظة الانضمام، ولا تتغير المواقف أبدًا بعد ذلك. لا يوجد يانصيب بشكل متعمد، ولا عشوائية، ولا يوجد مسار أولوية - في ظل الندرة، يكون ترتيب الوصول هو الطلب الوحيد الذي يقبله الزائرون على أنه عادل، وهو الوحيد الذي لا يمكن التلاعب به. يتم استبعاد القفز في قائمة الانتظار من الناحية الفنية على مستويين: أرقام الانتظار تنمو فقط، ويقارن فحص القبول رقم الزائر بالرقم المقبول حاليًا على الخادم - يتم إصدار رمز القبول فقط بمجرد مرور هذا الفحص، وتوقيعه بسر قائمة الانتظار. لا يمكن للزائر المطالبة بمركز أفضل، ويفشل الرمز المميز المزور في التحقق من صحة التوقيع. يقوم المشغلون الذين يحتاجون إلى تدفقات منفصلة - على سبيل المثال، غرفة انتظار واحدة لكل حدث أو لكل عملية بيع - بتشغيل غرف انتظار مستقلة متعددة، لكل منها مجموعة ثابتة وسر ومعدل وتكوين خاص بها.

العمارة تحت الحمل: الأرقام المقاسة

يتبع هدف التصميم مباشرة من منطق القبول أعلاه: نظرًا لأن الرقم المقبول مشتق من الوقت المنقضي ولا يقرأ التحقق من الحالة أي حالة لكل زائر، فإن حركة مرور الزائر بأكملها تقريبًا هي حساب عديم الحالة. يمكن لأي مثيل الرد على أي طلب، ولا تشارك المثيلات سوى قاعدة البيانات، ويضيف النظام الأساسي المثيلات تلقائيًا تحت التحميل. إن كتابة قاعدة البيانات الواحدة لكل زائر — الزيادة الذرية عند الانضمام — هي نقطة التسلسل الوحيدة، وتحدث مرة واحدة بالضبط لكل زائر، وليس لكل استطلاع. تأتي الأرقام أدناه من مشغل اختبار التحميل المدمج الموضح أعلاه، والذي تم قياسه عبر نقطة نهاية HTTPS العامة مقابل مثيل واحد لخدمة قائمة الانتظار؛ يجمع ملف التعريف المختلط بين الانضمام واستطلاع الحالة بما يتناسب مع مسار الزائر الحقيقي:

يجرينتيجة

mix · 10 req/s · 30 sالكمون ص50 7,6 ms · p95 12,0 ms · معدل الخطأ 0 %

mix · 25 req/s · 60 sالكمون ص50 7,3 ms · p95 11,4 ms · معدل الخطأ 0 %

mix · 50 req/s · 45 sالكمون ص50 6,7 ms · p95 11,0 ms · معدل الخطأ 0 %

status · 50 req/s · 45 sالكمون ص50 6,4 ms · p95 8,9 ms · معدل الخطأ 0 %

تم القياس في يوليو 2026 باستخدام مسار رمز الإنتاج؛ تكتمل كل عملية تشغيل بدون أخطاء وزمن وصول متوسط مكون من رقم واحد. يعالج مثيل واحد خمسين طلبًا في الثانية — عدة آلاف من الزائرين المنتظرين الذين يستقصون في الفترة الزمنية الموصى بها — دون بذل جهد كبير؛ وبعد ذلك، تتولى حالات إضافية المهمة. هذا القياس ليس مربعًا أسود: كل مثيل قيد التشغيل يُبلغ عن نفسه بشكل مستمر باستخدام المقاييس المباشرة - وحدة المعالجة المركزية، والذاكرة، وإنتاجية الطلب - المرئية في أي وقت في وحدة تحكم مسؤول ADITUS، لذا فمن الواضح عدد المثيلات التي تحمل نسخة معروضة للبيع ومقدار المساحة المتبقية. تعمل اختبارات التحميل المجدولة على إعادة التحقق من هذه الأرقام بشكل مستمر وفقًا لنظام الإنتاج، ويتم وضع علامة تلقائيًا على التشغيل الذي يتخلف بشكل واضح عن سابقاته.

نقاط النهاية

عشر نقاط نهاية، لا توجد مصادقة للزوار، يقتصر CORS على المجالات التي تم تكوينها لكل قائمة انتظار. تستخدم صفحة غرفة الانتظار المستضافة واجهة برمجة التطبيقات هذه بالضبط - ويمكن أيضًا توجيهها مباشرةً للحصول على تجربة انتظار مخصصة بالكامل. (API)

نقطة النهايةماذا يفعل

GET /queue/<slug>صفحة غرفة الانتظار المستضافة: تطلب رقمًا وتستقصي الحالة وتعيد توجيه الزائر تلقائيًا بمجرد قبوله.

POST /queue/<slug>/joinإصدار رقم انتظار (الكتابة الوحيدة في مسار الزائر). 423 أثناء إيقاف قائمة الانتظار مؤقتًا.

GET /queue/<slug>/status?number=Nاستقصاء حالة القبول لرقم ما - للقراءة فقط، ويتضمن رأس "إعادة المحاولة بعد". 404 للأرقام التي لم يتم إصدارها مطلقًا.

POST /queue/<slug>/tokenاستبدل الرقم المقبول برقم HS256 JWT الموقع. 425 بينما لم يتم قبول الرقم بعد، و404 للأرقام التي لم يتم إصدارها مطلقًا.

GET /queue/<slug>/enterنقطة دخول البوابة: يتم نشرها بدلاً من عنوان URL الخاص بالمتجر. إعادة التوجيه مباشرة إلى عنوان URL المستهدف الذي تم تكوينه (باستخدام رمز القبول) أثناء توفر السعة؛ وإلا فإنه يعيد التوجيه إلى غرفة الانتظار. يتطلب عنوان URL المستهدف الذي تم تكوينه. يقبل ?code=… لرموز تجاوز VIP: يتخطى الرمز الصالح قائمة الانتظار بالكامل، وينتقل الرمز غير الصالح إلى المسار العادي دون أي تلميح.

GET /queue/<slug>/embed.jsنص التكامل من جانب المتجر: يسمح للزوار بالدخول بصمت بينما لا أحد ينتظر؛ بمجرد تشكيل قائمة الانتظار، يقوم بتوجيه الزائرين دون تصريح مرور صالح إلى غرفة الانتظار وإعادتهم إلى الصفحة المحددة التي أتوا منها.

GET /queue/<slug>/verify?token=…التحقق من الرمز المميز من جانب الخادم الذي يستخدمه البرنامج النصي للتكامل: التحقق من صحة التوقيع والجمهور وانتهاء صلاحية رمز القبول.

GET /queue/<slug>/infoمعلومات قائمة الانتظار العامة: العلامة النشطة والرقم المسموح به حاليًا وعدد الانتظار.

POST /queue/<slug>/heartbeatإشارة وجود لاكتشاف التخلي الاختياري: تشير صفحة غرفة الانتظار إلى أن الرقم لا يزال موجودًا. يتم القبول بصمت أثناء إيقاف الكشف.

POST /queue/<slug>/bypassاسترد رمز تجاوز VIP عبر JSON: يُرجع رمز القبول بالإضافة إلى عنوان URL المستهدف. جميع الرموز غير الصالحة، ومنتهية الصلاحية، والمستنفدة، والمعطلة تنتج نفس 404 - لا يوجد أوراكل لتخمين التعليمات البرمجية.

GET /queue/<slug>/powتحدي إثبات العمل لحماية الروبوت الاختيارية: تم تمكين الإرجاعات: خطأ أثناء إيقاف الحماية؛ وإلا فسيتم حل التحدي الموقع الذي يتوقع /join حله.

GET /queue/healthzفحص الصحة العامة لمراقبة وقت التشغيل: إجابات بدون مصادقة وبدون الوصول إلى قاعدة البيانات. تم استبعادها عمدًا من مقاييس المثيل، لذا فإن مراقبة أصوات الاتصال لا تؤدي أبدًا إلى تشويه صورة حركة المرور.

1. اطلب رقم انتظار

join.ts

// Wartenummer anfordern (einziger Schreibzugriff im Besucherpfad).
const res = await fetch("https://developers.aditus.com/queue/<slug>/join", {
  method: "POST",
});
const ticket: {
  queue: string;              // Queue-Slug
  name: string;               // Anzeigename des Warteraums
  number: number;             // vergebene Wartenummer
  serving: number;            // bis zu dieser Nummer wird weitergeleitet
  ahead: number;              // Anzahl Nummern vor dieser
  admitted: boolean;          // true -> sofort weiter zu /token
  estimatedWaitSeconds: number;
  retryAfterSeconds: number;  // empfohlenes Polling-Intervall
} = await res.json();
// 423 Locked -> der Warteraum ist pausiert (keine Weiterleitung, keine neuen Nummern).

2. استطلاع الحالة

status.ts

// Statusabfrage — rein lesend, beliebig oft wiederholbar.
// Der Server sendet zusätzlich einen Retry-After-Header.
const res = await fetch(
  "https://developers.aditus.com/queue/<slug>/status?number=" + ticket.number,
);
const status: {
  queue: string;
  name: string;
  active: boolean;            // false -> Weiterleitung pausiert
  number: number;
  serving: number;
  ahead: number;
  admitted: boolean;
  estimatedWaitSeconds: number;
  retryAfterSeconds: number;
} = await res.json();

if (status.admitted) {
  // -> Token abholen und zum Shop weiterleiten
}

3. إحضار رمز القبول

token.ts

// Sobald admitted=true: Zugriffs-Token abholen.
const res = await fetch("https://developers.aditus.com/queue/<slug>/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ number: ticket.number }),
});
// 425 Too Early -> die Nummer ist noch nicht zur Weiterleitung freigegeben.
const grant: {
  queue: string;
  number: number;
  token: string;              // signierter HS256-JWT
  tokenType: "JWT";
  expiresInSeconds: number;   // Standard: 600 s
  targetUrl: string | null;   // konfiguriertes Weiterleitungsziel
} = await res.json();

// Weiterleitung übernimmt die gehostete Warteraum-Seite automatisch:
// targetUrl + "?aditus_queue_token=" + grant.token

اختياري: التحقق من الرمز المميز في الواجهة الخلفية لديك

يكتمل تكامل علامة البرنامج النصي من تلقاء نفسه. يمكن للمتاجر التي تتحكم في الواجهة الخلفية الخاصة بها أيضًا التحقق من رمز القبول هناك: إنه HS256 JWT قياسي، تم التحقق منه دون الاتصال بالإنترنت باستخدام السر المشترك - لا يوجد رد اتصال بقائمة الانتظار، ولا يوجد زمن انتقال إضافي. يتم إنشاء السر عند إنشاء قائمة الانتظار، ويظهر مرة واحدة بالضبط، ويمكن تدويره في أي وقت. المطالبات: iss دائمًا عبارة عن قائمة انتظار aditus، وaud هو سبيكة قائمة الانتظار، وqnr هو رقم الانتظار المقبول، وحدود صلاحية الصلاحية (الافتراضي 10 دقائق). ملحوظة: المرور الصامت تحت معدل القبول لا ينتج رمزًا مميزًا - الواجهة الخلفية التي تتطلب رمزًا مميزًا بشكل صارم يجب أن ترسل الزائرين بدون رمز مميز إلى غرفة الانتظار، والتي تصدر بعد ذلك رمزًا مميزًا على الفور عندما لا ينتظر أحد.

verify.ts

// ZIELSYSTEM (dein Shop / deine Seite): Token prüfen — Standard-JWT (HS256).
// Das Secret erhältst du einmalig von ADITUS beim Einrichten des Warteraums.
import jwt from "jsonwebtoken";

const payload = jwt.verify(token, process.env.ADITUS_QUEUE_SECRET!, {
  algorithms: ["HS256"],
  issuer: "aditus-queue",     // iss ist immer aditus-queue
  audience: "<slug>",         // aud ist der Queue-Slug deines Warteraums
}) as { qnr: number; iat: number; exp: number };

// payload.qnr = die weitergeleitete Wartenummer.
// Gültiger Token -> Besucher passieren lassen (z. B. Cookie setzen).
// Fehlender/ungültiger Token -> zurück in den Warteraum:
//   https://developers.aditus.com/queue/<slug>

الأمن في مكان واحد

تم وصف آليات الأمن حيث تنتمي في التدفق أعلاه؛ هذا القسم يجمعهم. الرموز المميزة: رموز القبول هي HS256 JWTs، موقعة بسر لكل قائمة انتظار يظهر مرة واحدة بالضبط ويمكن تدويره في أي وقت؛ ربط الجمهور (قائمة الانتظار) وانتهاء الصلاحية القصير (افتراضي 10 دقائق) يحدان من قيمة الرمز المميز الذي تم التقاطه. حماية الروبوتات: يؤدي فحص إثبات العمل الاختياري إلى جعل الانضمام الجماعي من مزارع الروبوتات مكلفًا نسبيًا؛ التحديات موقعة بواسطة HMAC وتنتهي بعد خمس دقائق؛ بالإضافة إلى ذلك، يعمل الحارس الذي يبذل أفضل جهد لكل مثيل على منع إعادة استخدام التحدي المستنفذ - محرك التكلفة الحقيقي هو عمل التجزئة نفسه. عمليات إعادة التوجيه: يتم التحقق من صحة عناوين URL المرتجعة من جانب الخادم مقابل النطاقات التي تم تكوينها لكل قائمة انتظار - لا تصبح غرفة الانتظار إعادة توجيه مفتوحة أبدًا. سطح واجهة برمجة التطبيقات (API): لا تحمل نقاط نهاية الزائر أي بيانات اعتماد على الإطلاق، ويتم تقييد CORS لكل قائمة انتظار، ويستخدم وصول المسؤول مفاتيح واجهة برمجة التطبيقات المرتبطة بغرفة انتظار واحدة، ويتم تخزينها فقط كتجزئة، ولا يمكنها إدارة مفاتيح أخرى وترك مسار تدقيق. ارتفاع حركة المرور: تمتص البنية عديمة الحالة الحمل حسب التصميم - أي مثيل يجيب على أي طلب، وتقوم المنصة بقياس المثيلات تلقائيًا؛ يتم توفير تصفية DDoS على مستوى الشبكة بواسطة منصة الاستضافة أمام الخدمة.

أوضاع الفشل: ماذا يحدث عندما ينكسر شيء ما

توجد غرفة الانتظار أمام الإيرادات - سلوكها الفاشل مهم بقدر أهمية مسارها السعيد.

خدمة قائمة الانتظار غير قابلة للوصول (متغير علامة البرنامج النصي): فشل البرنامج النصي في الفتح - يظل المتجر قابلاً للاستخدام بالكامل. انقطاع التيار الكهربائي في غرفة الانتظار لا يمنع المتجر أبدًا.
خدمة قائمة الانتظار غير قابلة للوصول (متغير البوابة): الإدخالات الجديدة مؤقتة؛ الزوار الذين تم قبولهم بالفعل موجودون في المتجر ويستمرون دون أن يتأثروا.
فقدان مثيل واحد: لا إشعارات الزائر. لا توجد حالة لكل زائر في أي مثيل - كل مثيل يجيب على كل طلب، وقاعدة البيانات المشتركة هي المكون الوحيد ذو الحالة.
تحديث المتصفح: يتم الاحتفاظ برقم الانتظار في جلسة المتصفح — إعادة التحميل تعود إلى نفس الموضع، ولا يتم فقدان المكان في الطابور أبدًا.
يقوم الزائر بمسح ملفات تعريف الارتباط أو تخزين المتصفح: لا يمكن استرداد الموضع عمدًا - يرسم الزائر رقمًا جديدًا في نهاية السطر. أي شيء آخر من شأنه أن يفتح الطريق أمام الاحتيال.
تم إيقاف غرفة الانتظار مؤقتًا: يتوقف الانضمام والقبول بإشارة واضحة (HTTP 423) ورسالة توضيحية في غرفة الانتظار - لا توجد أخطاء صامتة.
فشل فحص صحة المتجر (المعدل التلقائي): يتجمد السعر أولاً، ثم ينخفض إلى الحد الأدنى الذي تم تكوينه - لا يفتح فحص الصحة الذي لا يمكن الوصول إليه البوابات على نطاق أوسع أبدًا.

كيف يقارن هذا بمنتجات غرف الانتظار المخصصة

تعالج ADITUS-Queue نفس المشكلات التقنية التي تعالجها منتجات غرف الانتظار الافتراضية المخصصة للمؤسسات. يوضح الجدول الإمكانيات التي يتم قياس هذه المنتجات من خلالها لكيفية تغطية ADITUS-Queue لها - بما في ذلك إغفال واحد متعمد.

القدرةفي قائمة انتظار ADITUS (ADITUS-Queue)

الإنصافFCFS صارمة عن طريق الزيادة الذرية؛ القفز على قائمة الانتظار مستبعد من الناحية الفنية.

Fail-openمع تكامل علامة البرنامج النصي، لا يؤدي انقطاع غرفة الانتظار إلى حظر التطبيق المحمي أبدًا؛ لا يتأثر الزوار الذين تم قبولهم بالفعل في كل متغير.

إنفاذ الحافةالتحقق من الرمز المميز دون اتصال بالإنترنت في Nginx وCaddy وCloudflare وCloudFront - بدون أي زمن استجابة إضافي.

حماية البوتإثبات عمل اختياري لكل قائمة انتظار، غير مرئي للمتصفحات الحقيقية.

أداء مثبتالأرقام المقاسة المنشورة، والتي يتم إعادة التحقق منها باستمرار من خلال اختبارات الحمل المجدولة على الإنتاج.

القبول التكيفيمعدل التنظيم الذاتي مدفوع بالفحص الصحي للتطبيق المحمي.

API-firstتعتبر كل قدرة زائر ومشرف بمثابة نقطة نهاية REST موثقة.

الأولوية / الممرات VIPلم يتم تقديمه عمدًا - أمر الوصول الصارم هو الوعد بالعدالة. تعمل الجماهير المنفصلة كغرف انتظار منفصلة.

الإدارة عبر مفتاح API

كل ما تفعله وحدة تحكم المشرف ADITUS لغرفة انتظار واحدة - ضبط معدل القبول، والإيقاف المؤقت، وتغيير التكوين - متاح أيضًا للأجهزة. يستخدم Access مفتاح API مع البادئة qak_، ويتم إرساله كرمز مميز لحامله؛ يتم إنشاء كل مفتاح لغرفة انتظار واحدة فقط ويمكنه قراءة تلك الغرفة وتغييرها فقط. يتم إنشاء المفاتيح وإبطالها في وحدة تحكم المشرف، ويتم عرضها مرة واحدة بالضبط ويتم تخزينها كتجزئة فقط. حالة الاستخدام النموذجية هي دليل التشغيل المعروض للبيع: تعمل المهمة المجدولة على رفع معدل القبول قبل البدء مباشرة، ويقوم البرنامج النصي بإيقاف قائمة الانتظار مؤقتًا في حالة الطوارئ، وتقرأ المراقبة التكوين الحالي. يتم تطبيق ثلاثة حواجز حماية: لا يصل المفتاح مطلقًا إلى غرف الانتظار الأخرى أو وظائف الإدارة العامة (اختبارات التحميل، والجداول الزمنية، والمثيلات) - يتم رفض هذه الطلبات من جانب الخادم؛ إدارة المفاتيح نفسها غير ممكنة عن عمد باستخدام مفتاح - لا يمكن للمفتاح المسرب أبدًا إنشاء أو إدراج مفاتيح أخرى؛ ويتم تسجيل كل تغيير يتم إجراؤه باستخدام المفتاح في سجل التدقيق تحت اسم المفتاح وغرفة الانتظار الخاصة به. (Bearer)

أمثلة مع الضفيرة (curl)

# Konfiguration des zugeordneten Warteraums lesen. Jeder Key ist an genau
# einen Warteraum gebunden — die Liste enthält daher höchstens diesen einen
# Eintrag; andere Warteräume und globale Verwaltungsfunktionen sind mit
# einem Key nicht erreichbar.
curl -H "Authorization: Bearer qak_…" \
  https://developers.aditus.com/api/admin/queue/sites

# Weiterleitungsrate im laufenden Betrieb anheben: Lesen -> Feld ändern -> Schreiben.
# PATCH erwartet die vollständige Konfiguration (ohne slug); unbekannte
# Felder wie id oder Zeitstempel werden serverseitig ignoriert.
KEY="qak_…"; BASE="https://developers.aditus.com/api/admin/queue"
SITE=$(curl -s -H "Authorization: Bearer $KEY" "$BASE/sites" \
  | jq '.sites[0]')
echo "$SITE" | jq '.ratePerMinute = 300' | curl -s -X PATCH \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d @- "$BASE/sites/$(echo "$SITE" | jq -r .id)"

# Zugeordneten Warteraum pausieren (keine Weiterleitung, keine neuen Nummern):
# active = false
echo "$SITE" | jq '.active = false' | curl -s -X PATCH \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d @- "$BASE/sites/$(echo "$SITE" | jq -r .id)"

تمت جدولته عبر إجراءات GitHub (GitHub Actions)

# .github/workflows/onsale.yml — Weiterleitungsrate zum Vorverkaufsstart anheben.
# Den API-Key als Repository-Secret ADITUS_QUEUE_API_KEY hinterlegen. Der Key
# ist an den Warteraum des Vorverkaufs gebunden — mehr kann er nicht.
name: Weiterleitungsrate zum On-Sale anheben
on:
  schedule:
    - cron: "55 8 14 3 *"   # 14. März, 08:55 UTC — kurz vor dem On-Sale
  workflow_dispatch: {}

jobs:
  raise-rate:
    runs-on: ubuntu-latest
    steps:
      - name: Rate auf 300/min anheben
        env:
          KEY: ${{ secrets.ADITUS_QUEUE_API_KEY }}
        run: |
          BASE="https://developers.aditus.com/api/admin/queue"
          # Der Key sieht nur seinen gebundenen Warteraum — .sites[0] genügt.
          SITE=$(curl -sf -H "Authorization: Bearer $KEY" "$BASE/sites" \
            | jq '.sites[0]')
          echo "$SITE" | jq '.ratePerMinute = 300' \
            | curl -sf -X PATCH \
              -H "Authorization: Bearer $KEY" \
              -H "Content-Type: application/json" \
              -d @- "$BASE/sites/$(echo "$SITE" | jq -r .id)"