Skip to content

4.0.0 — four transports, and the queue is a setting

Choose a tag to compare

@CorneiZeR CorneiZeR released this 31 Aug 22:02
· 161 commits to master since this release
ce26dca

The package is django-aiogram, and the queue is a setting. Redis was the transport; it is now
one of four, and which one carries a message is BROKER. Handlers stay ordinary Django app code and
bot.send() still works from anywhere in the project.

pip install 'django-aiogram[redis]'                 # Redis list, the default, or Redis Streams
pip install 'django-aiogram[rabbitmq,redis]'        # RabbitMQ
pip install 'django-aiogram[kafka,redis]'           # Kafka

One extra per transport, for the queue. redis is in the other two lines for the FSM store:
FSM_STORAGE defaults to aiogram's Redis one, so a bot keeping chat state needs that driver
whichever transport carries its messages — FSM_STORAGE: 'memory' is what drops it, and
E019 says so at startup rather than letting the dispatcher fail.

Upgrading from 3.x is a rename, an extra and a migrate, in that order — Upgrading walks it
step by step, including what to do with the old event-log table. It was rehearsed end to end on a
real consumer project before this tag: a 3.1 install with rows on the old table and messages on the
list, and a clean install into a database that had never seen the package.

Four transports

transport BROKER extra
Redis list (default) django_aiogram.broker.redis_list.RedisListBroker [redis]
Redis Streams django_aiogram.broker.redis_streams.RedisStreamsBroker [redis]
RabbitMQ django_aiogram.broker.rabbitmq.RabbitMQBroker [rabbitmq]
Kafka django_aiogram.broker.kafka.KafkaBroker [kafka]

Your code does not change with the row: same bot.send(), same handlers, same event log, same
manage.py start_tgbot. What differs is what becomes of a message whose worker was killed
mid-send, and what recovery is — a command, a clock, or the broker's own doing. Each transport has
a page of its own, with the guarantee it gives and what a publish costs, measured.

No driver is a dependency of this package any more. pip install django-aiogram imports and
runs manage.py; the transport you name brings its own driver, and manage.py check refuses at
startup with the pip install line when the two disagree.

Renames, and what to do about them

  • the distribution and import path are django-aiogram / django_aiogram, the environment prefix
    is DJANGO_AIOGRAM_, the logger is django_aiogram, check ids read django_aiogram.EXXX;
  • send_redis → enqueue, asend_redis → aenqueue; get_redis and redis_conn moved to
    django_aiogram.redis; bot.send() is untouched;
  • the event log has a table of its own, django_aiogram_event. The 3.x table is left exactly where
    it is — manage.py tgbot_move_events copies its rows in bounded, resumable chunks, and
    I003 says it is there to be copied;
  • DELIVERY takes a dotted path, so a consumer you write goes in it. DeliveryKind is gone;
  • src/ groups by what a thing is for, so several import paths moved. Two are ones a project wrote
    down itself — DATABASE_ROUTERS and the webhook view in urls.py — and E048 catches the first.

Nothing is aliased. An alias that outlives the release it was written for becomes a second name for
the same thing for ever, so each old name is listed against its replacement on Upgrading
instead.

Also in this release

  • A short id on every event-log row, twelve characters of the correlation id in Crockford's
    base32, searchable in the admin. manage.py tgbot_backfill_short_ids fills rows written before it.
  • The bot process resets a dead database connection, which it never did: close_old_connections()
    is wired to request signals and a bot worker has no requests. Measured in production — a Postgres
    restart left every handler raising InterfaceError for ten hours while the probe said healthy.
  • The container probe runs on every transport, including an install with no redis-py at all.
    One refusal changed wording with it: redis is unreachable is now the broker is unreachable.
  • The transport is closed at shutdown, which it never was — worst on Kafka, where a member that
    disappears without leaving its group holds its partitions until the session times out.
  • Both blocking deadlines come from the transport being read, not from REDIS_TIMEOUT, which
    three of the four never read. W004 names the setting your deployment actually has.

The full entry, with every measurement and the decisions behind them, is in
CHANGELOG.md.