s3 support

.env.example

@@ -239,6 +239,33 @@ TELESRV_BOT_VERIFICATION_ENABLED=true
 # weights and recompute timing live in the Advanced section below.
 TELESRV_RATING_ENABLED=true
 
+## Storage & Media -- Where uploaded media is stored, and how the server reacts to running low on space.
+
+# Where uploaded media (photos, documents, stickers) is physically stored.
+# "localfs" writes to TELESRV_BLOB_DIR on this machine's disk. "s3" writes to
+# an S3-compatible object store -- self-hosted MinIO or AWS S3 -- configured
+# below. Switching only affects new uploads; existing files stay wherever
+# they were written and remain readable.
+TELESRV_BLOB_BACKEND=localfs
+# Only used when TELESRV_BLOB_BACKEND=s3.
+TELESRV_S3_ENDPOINT=
+TELESRV_S3_REGION=us-east-1
+TELESRV_S3_BUCKET=
+TELESRV_S3_ACCESS_KEY_ID=
+TELESRV_S3_SECRET_ACCESS_KEY=
+TELESRV_S3_USE_SSL=true
+# MinIO typically needs this on (bucket in the URL path); AWS S3 does not.
+TELESRV_S3_PATH_STYLE=false
+# Reject new uploads once storage is nearly full, instead of letting the disk
+# fill up. Thresholds live in the Advanced section below.
+TELESRV_STORAGE_LOW_SPACE_GUARD_ENABLE=true
+# Automatically delete old media once it's no longer referenced by any
+# message, profile photo, or sticker set (never deletes media still visible
+# in a conversation). Off by default -- storage usage is tracked and shown
+# in the admin panel either way; enable this once you're comfortable with
+# what it will reclaim. Retention age lives in the Advanced section below.
+TELESRV_STORAGE_RETENTION_ENABLE=false
+
 
 # ==============================================================================
 # Advanced / internal tuning
@@ -367,6 +394,23 @@ TELESRV_STICKER_SEED_MAX_SETS=300
 # Sticker set auto-installed for every newly registered account; <=0 disables this.
 TELESRV_DEFAULT_STICKER_SET_ID=0
 
+# Storage low-space guard thresholds (master toggle is TELESRV_STORAGE_LOW_SPACE_GUARD_ENABLE above).
+# localfs: reject new uploads once real free disk bytes fall below this; <=0 disables.
+TELESRV_STORAGE_MIN_FREE_BYTES=1073741824
+# Reject new uploads once total tracked blob bytes would exceed this. The only
+# meaningful "low space" signal on the s3 backend (no OS free-space concept);
+# optional soft cap on localfs too. <=0 disables.
+TELESRV_STORAGE_MAX_TOTAL_BYTES=0
+# How often the cached free-space/usage gauge behind the guard above refreshes.
+TELESRV_STORAGE_USAGE_REFRESH_INTERVAL=1m
+# Storage retention sweep tuning (master toggle is TELESRV_STORAGE_RETENTION_ENABLE above).
+# How long a document/photo must have had zero references before the sweep
+# deletes it -- not how old the media itself is, and it never touches media
+# still referenced by a live message/profile-photo/sticker-set. The sweep
+# itself runs alongside every other retention check on the shared
+# TELESRV_RETENTION_INTERVAL/TELESRV_RETENTION_BATCH cadence above.
+TELESRV_STORAGE_RETENTION_MAX_AGE=720h
+
 # New-account perks: free Telegram Premium months and starting Stars balance.
 TELESRV_PREMIUM_GRANT_MONTHS=3
 TELESRV_STARS_STARTING_GRANT=1000