.. include:: ../variables.rst
.. _challenges-auto-close:

Scheduled Auto-Close
====================

Most challenges follow a simple pattern: they run for a fixed period, then an administrator needs
to remember to press :blue:`Close Challenge` to award the winners. **Auto-close** removes the
"remember to press the button" step.

.. figure:: /images/challenges/lightmode/auto-close-toggle.png
   :align: center
   :width: 60 %

|br|

Enabling auto-close on a challenge
----------------------------------

On the :ref:`challenges-detail` editor, tick the **Auto-close on end date** checkbox. Save.

A challenge is eligible for auto-close when:

* ``autoclose = 1``
* ``closed = 0`` (hasn't been closed yet)
* ``enddate`` is in the past

The scheduled job
-----------------

The backend exposes a dedicated cron hook:

.. code-block:: none

   POST /challenges/autoclose-run

Each time the endpoint is hit, it:

#. Scans for challenges meeting the three conditions above.
#. For each, calls ``ResolveParticipants`` + ``ComputeChallengeMetric`` + ``WriteChallengeResults``
   to create the final snapshot.
#. Calls ``CloseChallenge`` to award points, grant badges, queue notifications, and flip
   ``closed = 1``.
#. Returns a JSON summary: ``{"success":true,"scanned":N,"closed":M}``.

Scheduling the job
------------------

The endpoint is idempotent and safe to call as often as you like -- challenges already closed
are skipped by the ``closed = 0`` filter. A reasonable schedule is **once an hour**:

.. code-block:: none

   0 * * * * curl -s -X POST https://your-server/challenges/autoclose-run

Or **once a day** if end dates always fall on day boundaries:

.. code-block:: none

   15 1 * * * curl -s -X POST https://your-server/challenges/autoclose-run

Add the entry to |APPNAME|'s own cron management page, or to the operating system's crontab. The
endpoint accepts no authentication by default -- gate it at the HTTP layer if exposing to the
public internet.

What auto-close does **not** do
-------------------------------

* **Does not** extend the ``enddate``. Once past, the challenge closes on next scan.
* **Does not** send a summary email to administrators. (Coming in a future release.)
* **Does not** re-open a closed challenge or roll back an early close.
* **Does not** affect challenges with ``autoclose = 0`` -- those still require a manual close.

Manual override
---------------

An administrator can still press :blue:`Close Challenge` on an auto-close challenge at any time
before the end date. The early close is recorded with the same idempotent semantics; the
scheduled job will then skip this challenge because ``closed = 1``.

Troubleshooting
---------------

* *"My challenge ended yesterday but is still active."* -- Check that :blue:`Auto-close on end
  date` is ticked (not just :blue:`Active`). The two flags are independent.
* *"The cron is running but nothing is closing."* -- Hit the endpoint manually and read the
  response. ``scanned=0`` means no challenges match the eligibility window; ``scanned>0,
  closed=0`` means compute or close failed (check the server log for ``HandleChallengeAutoCloseRun``
  entries).
* *"I want to close a challenge earlier than its end date."* -- Either edit the end date then hit
  the cron, or just press :blue:`Close Challenge` manually.