Telnet, session és store

A rubbs legalja: hogyan lesz egy kapcsolatból BBS::Session, mit csinál a telnet-egyeztetés, az ablakméret (NAWS), a readkey összes lehetséges billentyűje, a readline, az írás, az egérjelentés, az idle-korlátok és a bontás (lib/bbs/server.rb, session.rb, telnet.rb); valamint a BBS::Store, a tábla, amelyben a board a hívói adatait tartja, a 0.33.0 óta SQLite-fájlban (lib/bbs/store.rb). A többi építőelem, ami egy tartalmas boardnak kell (SQLite, HTTP, cache, rate limit, naplózás), az Adat és hálózat oldalon van. A legtöbb board ezekkel csak egy Flow-n vagy egy Applicationön keresztül találkozik; közvetlenül egy Flow call lépésében, egy doorban vagy egy C64-es arcban van rájuk szükség.

A kapcsolattól a sessionig

BBS.start és BBS::Server

BBS.start                 # port from BBS.config.port (ENV['BBS_PORT'] or 2323)
BBS.start(port: 2400)

A BBS.start(port: config.port) a BBS::Server.new(port:).run-t futtatja, ami blokkol:

1. a 0.0.0.0:PORT-on figyel (kiírja: BBS listening on port …);
2. minden kapcsolatnál ellenőrzi a korlátokat: ha már max_sessions hívó van bent, kiírja, hogy Too many callers right now, try again later., naplózza: BBS busy: …, és bont; ha arról a címről már max_sessions_per_ip hívás fut, azt írja ki, hogy Too many calls from your address, try again later., és BBS crowded: …-ot naplóz;
3. szálat indít, a socket olvasási/írási időkorlátját idle_seconds-ra állítja (nil esetén 900 s; ehhez a Ruby 3.2 IO#timeout=-ja kell), és egy új BBS::Session-t futtat;
4. Session#run: negotiate, enable_mouse, ha a config.mouse és a config.mouse_on_connect is be van kapcsolva, majd FlowRunner.new(session, session_id, config.flow).run; utána mindig kikapcsolja az egeret és lezárja a socketet;
5. amikor a session véget ér, bárhogy is, a szál csökkenti a számlálót, és meghívja a config.on_session_end-et.

Minden sor a BBS.log-on át megy, és a config.log_tag-gel kezdődik (lásd Adat és hálózat). A bontás vagy az elnémult vonal (IOError, EPIPE, ECONNRESET, ETIMEDOUT, IO::TimeoutError) feedia-bbs: session: dropped by the client (…) formában kerül a naplóba, nem hibaként. Minden más kivételt a session címke alatt naplóz, az osztályával, az üzenetével és három sor backtrace-szel. Magának az accept-nek a hibáinál (ECONNABORTED, EMFILE, ENFILE) a ciklus naplóz, és fél másodpercet vár ahelyett, hogy pörögne. Ctrl-C-re és SIGTERM-re (docker stop) kiírja: Server stopped..

A réteg config-mezői

require 'bbs'

BBS.configure do |c|
  c.port           = 2400
  c.idle_seconds   = 600
  c.max_sessions   = 20
  c.on_session_end = ->(session) { puts "#{session.session_id} left (#{session.term_cols}x#{session.term_rows})" }
  c.flow = BBS::Flow.define do
    say 'Hello!'
  end
end

BBS.start

Telnet-egyeztetés

Közvetlenül a kapcsolódás után a session négy telnet-parancsot küld, és amíg mást nem hall, 80×24-es ablakot feltételez:

A kliens válaszait (WILL/WONT/DO/DONT + opció) ott olvassa be és dobja el, ahol épp érkeznek: a readkey-ben, a readline-ban, a settle-ben. Más opciókezelés nincs (se BINARY, se TTYPE). Mindezt egyetlen IAC-értelmező végzi, a BBS::Telnet::Parser (1.0.0 óta), ugyanaz, amelyet egy gateway mindkét irányban használ. Egy telnetet egyáltalán nem beszélő kliens (WiFi-modem mögötti C64, nc) egyszerűen sosem válaszol.

NAWS: az ablakméret

Amikor a kliens jelenti a méretét (IAC SB NAWS w1 w2 h1 h2 IAC SE), a session frissíti a term_cols-t és a term_rows-t:

• az oszlopszám 20–255, a sorszám 8–100 közé szorul (0.33.0 óta); a nulla figyelmen kívül marad (a régi érték megmarad);
• a jelentésen belüli escape-elt 255 (IAC IAC) 255-ként olvasódik;
• egy alegyeztetésből legfeljebb 64 bájtot olvas, a többit eldobja (egy 65535×65535-ös jelentés nem tud gigabájtokat foglaltatni minden rendereléssel);
• jelentés bármikor jöhet: az átméretezett ablakot a következő olvasás észreveszi, és egy Application újrarendezi az ablakait;
• PETSCII-vonalon (a petscii! után) a méret 40×25 marad, de a naws_reported? ettől még igaz lesz.

A settle-t használja a BBS::Terminal.guess is, hogy egy modern terminált megkülönböztessen egy C64-től. Olcsó botszűrő is lesz belőle:

BOT_FILTER = BBS::Flow.define do
  call do |_ctx, runner|
    session = runner.session
    next nil if session.settle(timeout: 2)

    session.write "This board needs a telnet client that reports its window size.\r\n"
    :halt
  end
  say 'Welcome, human.'
end

A :halt-ot visszaadó call lépés befejezi a flow-t; a next egy értékkel lép ki a blokkból.

Billentyűk olvasása: readkey

key = session.readkey                # blocks until a key (or the socket timeout)
key = session.readkey(timeout: 1.0)  # :idle when nothing came in 1 s

Ezek egyikét adja vissza:

• egykarakteres String — nyomtatható karakter, UTF-8 is ("a", " ", "é", "ő");
• Symbol — egy nevesített billentyű (lásd a táblázatot);
• BBS::Telnet::MouseEvent — egérjelentés (csak bekapcsolt jelentésnél);
• :idle — letelt a timeout, és nem jött billentyű;
• nil — a hívó bontott.

A közben érkező telnet-parancsokat és NAWS-jelentéseket feldolgozza, sosem adja vissza. timeout nélkül az olvasás addig vár, amíg a socket saját időkorlátja (idle_seconds, alapból 900 s) IO::TimeoutError-t nem dob, ami egy IOError.

Billentyű-szimbólumok

Módosítók. Az xterm a Shiftet, az Altot és a Ctrl-t egy második CSI-paraméterként jelenti: az ESC [ 1 ; 2 A a Shift-Fel, az ESC [ 15 ; 5 ~ a Ctrl-F5. A rubbs előtagot tesz a billentyű szimbóluma elé:

A CSI-alakokra vonatkozik: nyilak, Home/End, Insert/Delete, Page Up/Down és a ~-os funkcióbillentyűk. Az xterm ESC [ 1 ; 5 P alakú módosított F1–F4-ét nem dekódolja, az :escape-ként olvasódik.

Más bájtok (NUL, 1c–1f, egy törött UTF-8 szekvencia) kimaradnak. PETSCII-vonalon a billentyűk a C64-éi: lásd Commodore 64.

Egéresemények

Bekapcsolt egérjelentésnél (enable_mouse) a kattintások, a húzások és a görgő BBS::Telnet::MouseEvent-ként jönnek vissza, ami egy Struct:

Mindkét jelentésformátumot olvassa: az SGR-t (ESC [ < b ; x ; y M lenyomás, … m felengedés) és a régi X10-et (ESC [ M b x y, mindegyik plusz 32).

Egy Application a MouseEventekből BBS::Event-eket csinál a widgeteknek; egy Door a programja idejére kikapcsolja a jelentést. Nyers call lépésben úgy kapod meg őket, ahogy jönnek.

Példa: nyers billentyűciklus

Egy call lépés, amíg fut, az övé a vonal. Ez kiír minden billentyűt, amit olvas, Esc-re vagy 30 tétlen másodperc után megáll, és túléli a bontást:

require 'bbs'

KEYS = BBS::Flow.define do
  call do |_ctx, runner|
    s = runner.session
    s.settle                       # wait for NAWS, or term_cols is still the default 80
    s.enable_mouse
    s.write "#{s.term_cols}x#{s.term_rows}, NAWS: #{s.naws_reported?}. Press keys, Esc ends.\r\n"
    idle = 0
    loop do
      key = s.readkey(timeout: 1)
      break if key.nil? || key == :escape

      if key == :idle
        idle += 1
        break if idle >= 30

        next
      end
      idle = 0
      text = key.is_a?(BBS::Telnet::MouseEvent) ? "#{key.kind} #{key.button} at #{key.x},#{key.y}" : key.inspect
      s.write "\e[1;33m#{text}\e[0m\r\n"
    end
    s.disable_mouse
    nil
  end
  say 'Bye.'
end

BBS.configure { |c| c.flow = KEYS }
BBS.start

A hívás első lépése rögtön az egyeztetés elküldése után fut, mielőtt a kliens válaszai megérkeznének: settle nélkül a term_cols és a term_rows még 80×24 lenne, a naws_reported? pedig hamis. A ciklusból break-kel lépj ki, ne return-nel: a blokkon belüli return LocalJumpError-t dob (a FlowRunner hibaként kiírja, és megy tovább).

Amit néhány, tesztszkriptből küldött bemenetre kiírt (100×30-as NAWS-szal):

a                  "a"
ESC [ A            :up
ESC [ 1 ; 2 A      :shift_up
ESC [ 15 ; 5 ~     :ctrl_f5
ESC O P            :f1
ESC [ Z            :shift_tab
ESC x              :alt_x
ESC CR             :alt_enter
01                 :ctrl_a
03                 :interrupt
7f                 :backspace
c3 a1              "á"
ESC [ < 0;10;5 M   press left at 10,5
ESC [ < 64;3;4 M   wheel up at 3,4
ESC [ < 2;7;8 m    release right at 7,8
ESC [ 1 ; 6 C      :ctrl_shift_right
ESC [ 24 ~         :f12

Példa: nyilakkal vezérelt menü

require 'bbs'

MENU = BBS::Flow.define do
  call do |ctx, runner|
    s     = runner.session
    items = %w[News Files Chat Logoff]
    pick  = 0
    loop do
      s.write "\e[2J\e[H"
      items.each_with_index do |item, i|
        s.write(i == pick ? "\e[7m > #{item} \e[0m\r\n" : "   #{item}\r\n")
      end
      key = s.readkey
      case key
      when nil then break
      when :up then pick = (pick - 1) % items.size
      when :down, :tab then pick = (pick + 1) % items.size
      when :enter
        ctx[:choice] = items[pick]
        break
      when String
        hit  = items.index { |i| i.downcase.start_with?(key.downcase) }
        pick = hit if hit
      end
    end
    nil
  end
  say 'Done.'
end

BBS.configure { |c| c.flow = MENU }
BBS.start

Sor olvasása: readline

name     = session.readline               # echoes what is typed
password = session.readline(mask: '*')    # echoes a * for each character

A Flow ask lépése ezt használja; egy call lépésben:

LOGIN = BBS::Flow.define do
  call do |ctx, runner|
    s = runner.session
    s.write 'Name: '
    ctx[:name] = s.readline or next :halt
    s.write 'Password: '
    password = s.readline(mask: '*') or next :halt
    next :halt unless password == 'secret'

    nil
  end
  say 'Logged in.'
end

Kipróbálva: a Zsé, Backspace, o, Enter "Zso"-t ad vissza (UTF-8); a maszkolt abc visszhangja ***.

Írás

A send_raw létezik, de privát (ezzel kerüli meg az egyeztetés és a petscii! az Encodert); kívülről a session.line-ra írj.

session.write "\e[1;32mOK\e[0m\r\n"
session.line.write "\x07".b          # a bell, past any encoder

A session azonosítója és állapota

Idle-korlátok, session-korlátok, bontás

Idle. A config.idle_seconds két helyen hat:

Max sessions. Egyszerre config.max_sessions (BBS_MAX_SESSIONS, különben 100) hívó, és egy nyilvános címről config.max_sessions_per_ip (BBS_MAX_SESSIONS_PER_IP, különben 6); a következő egy sort kap, a szerver bont, és BBS busy-t vagy BBS crowded-ot naplóz a két korláttal és a címmel (a stderr-re, puffer nélkül, így azonnal megjelenik a docker logs-ban). A max_sessions-t a konténer memóriájához kell méretezni: egy session nagyjából 0,5–1,7 MB a board saját 20–40 MB-ja fölött.

Bontás. Amikor a hívó bont:

• a readkey és a readline nil-t ad, a write csendben nil-t;
• a Flow IOError-t, EPIPE-ot vagy ECONNRESET-et dobó call lépése csendben leállítja a flow-t; nézd a nil-t és lépj ki break-kel, vagy dobj magad IOError-t (ahogy a C64-es képernyőosztályok teszik);
• a Session#run kikapcsolja az egeret és lezárja a socketet; a szerver session dropped-ot logol, és meghívja az on_session_end-et.

Perzisztencia: BBS::Store

A BBS::Store egy kis tábla, kulcsonként (általában session-azonosítónként) egy sorral: thread-safe, és ellenáll a bájtoknak, amiket egy terminál küldhet. A 0.33.0 óta egy SQLite-fájlban él (egy BBS::SQLite-ban, lásd Adat és hálózat); előtte CSV-fájl volt, és egy régebbi board CSV-jét az első használatkor beimportálja.

SESSIONS = BBS::Store.new(path: 'data/sessions.csv', headers: %w[session_id timestamp player_name code])

BBS::Store.new(path:, headers:)

A store.path, a store.database_path és a store.headers visszaadja őket.

Metódusok

Beszúrás (még nincs sor ezzel a kulccsal): a session_id a kulcs, a timestamp a pillanatnyi UTC-idő ISO 8601-ben (2026-10-27T22:15:45Z), a többi oszlop az azonos nevű mező (username: → username), üres (nil), ha nincs megadva.

Frissítés (a sor létezik): csak a megadott mezők változnak. A timestamp a beszúrás idejét őrzi. A nil-re állított mező üres string lesz.

A fejlécben nem szereplő mezőket figyelmen kívül hagyja, beszúrásnál és frissítésnél egyaránt.

Példa: oda-vissza

require 'bbs'

USERS = BBS::Store.new(path: 'data/users.sqlite3', headers: %w[session_id timestamp username email])

USERS.upsert(session_id: 'a1', username: 'joe', email: 'joe@example.com')
USERS.upsert(session_id: 'b2', username: 'ann')
USERS.upsert(session_id: 'a1', email: 'joe@new.example')

USERS.find('a1')
# => {"session_id"=>"a1", "timestamp"=>"2026-10-27T22:15:45Z", "username"=>"joe", "email"=>"joe@new.example"}
USERS.find('zz')            # => nil
USERS.all.size              # => 2
USERS.delete('b2')
USERS.all.map { |r| r['username'] }   # => ["joe"]

A sorok a data/users.sqlite3 store táblájában vannak; a sqlite3 data/users.sqlite3 'SELECT * FROM store' a board futása közben is megmutatja őket.

Egy régebbi board CSV-je

Ha a tábla még üres, és létezik az útvonal CSV-fájlja, a Store egy tranzakcióban beimportálja, majd átnevezi users.csv.imported-ra. Az a sor, amely nem érvényes CSV, több mezője van, mint a fejlécnek, vagy nincs session_id-ja, nem állítja meg az importot: a fejléc alá kerül a users.csv.rejected fájlba a sysopnak, és a naplósor megszámolja (store: 412 rows of data/users.csv imported into data/users.sqlite3, 2 set aside in data/users.csv.rejected). Hívd meg induláskor az open!-t, hogy ez még az első hívó előtt lezajoljon.

Tiszta értékek

Ezekbe a táblákba a hívók gépelnek, a terminál pedig bármit küldhet. Minden érték Stringgé alakul, és a BBS::Text.clean tisztítja meg: az érvénytelen UTF-8 bájtok kimaradnak, ahogy a C0 vezérlőkarakterek (a tab és az újsor marad), a DEL, a C1 vezérlők és a kétirányú szöveg felülíró karakterei is. Egy ANSI-szekvenciából csak az ESC bájt tűnik el: az "ann\e[31m" ann[31m-ként tárolódik.

s = BBS::Store.new(path: 'data/log.sqlite3', headers: %w[session_id name note])
s.upsert(session_id: 's1', name: "ann\e[31m\x00 bé", note: "two\nlines")
s.find('s1')
# => {"session_id"=>"s1", "name"=>"ann[31m bé", "note"=>"two\nlines"}

Szálak

Minden hívás egyetlen, zár mögötti közös kapcsolaton át éri el az SQLite-fájlt, így egy Store objektumot az összes session-szál megoszthat. A fájl WAL módban van: a board egy parancssori eszköze futás közben is olvashatja (és írhatja), a board pedig a következő hívásánál már látja a változást. Memóriabeli cache nincs többé.

Flow-val: persist

A Flow persist lépése context-kulcsokat ír egy store-ba, a session-azonosítóval mint kulccsal:

persist :player_name, :code, store: SESSIONS

A megnevezett kulcsok közül azokat veszi, amelyek benne vannak a contextben (a még be nem állítottak kimaradnak), és meghívja a store.upsert(session_id: a context session-azonosítója, **ezek)-et; ha egyik sincs beállítva, nem csinál semmit. Egy későbbi persist ugyanazt a sort frissíti. Lásd Flow.

Az Impostor BBS (bbs/impostor-bbs/lib/impostor.rb) így tart minden kihallgatást egyetlen store-ban:

module Impostor
  SESSION_HEADERS = %w[session_id timestamp player_name code feedback email].freeze

  def self.sessions_store(path) = BBS::Store.new(path: path, headers: SESSION_HEADERS)

  def self.debrief(sessions:, screens_dir:)
    BBS::Flow.define(screens_dir: screens_dir) do
      ask :player_name, prompt: 'Player Name', transform: :upcase
      ask :code,        prompt: 'Code'
      persist :player_name, :code, store: sessions
      # ...
      menu '>', loop: true do
        option 'Leave feedback' do
          ask :feedback, prompt: 'Feedback'
          persist :feedback, store: sessions
        end
        option 'Subscribe to updates' do
          ask :email, prompt: 'Email address', validate: :email
          persist :email, store: sessions
        end
        option('Exit') { exit_menu }
      end
    end
  end
end

# bbs.rb: one store, shared by both faces and every session
sessions = Impostor.sessions_store(File.expand_path('data/sessions.csv', __dir__)).open!

Flow-n kívül

A kulcs csak egy string: a hívó nevével kulcsolt store hívásokon át megőrzi az adatot.

PROFILES = BBS::Store.new(path: 'data/profiles.sqlite3', headers: %w[session_id timestamp calls last_seen])

def count_call(name)
  calls = PROFILES.find(name)&.fetch('calls').to_i
  PROFILES.upsert(session_id: name, calls: calls + 1, last_seen: Time.now.utc.iso8601)
end

Egy Application-handlerben vagy egy call lépésben a session-azonosító a ctx[:session_id] (Applicationön belül a context[:session_id]).

Ha kinövöd

A Store egyetlen, szöveges oszlopokból álló tábla, egyetlen stringgel kulcsolva. Egy board, amelynek posztjai, szálai vagy több táblája van, közvetlenül a BBS::SQLite-ot használja, saját sémával és számozott migrációkkal: lásd Adat és hálózat.

Lásd még

• rubbs — az áttekintés
• Első lépések — BBS.configure és az első board
• Flow — ask, persist, call
• Application — az ezekből a billentyűkből épülő események
• Commodore 64 — a PETSCII-vonal és a billentyűi
• Doorok — a vonal továbbadása
• Adat és hálózat — SQLite, HTTP, cache, rate limit, naplózás