Od bardzo dawna fascynuje mnie kultura Japonii. Jedną z rzeczy, które zawsze zwracały moją uwagę, jest długowieczność i ogólnie dobry stan zdrowia Japończyków.

Ciekawym elementem japońskiej kultury jest to, że ludzie spędzają dużo czasu, siedząc na podłodze. Większość z was zapewne widziała w japońskich filmach sceny, w których ludzie siedzą na podłodze wokół niskiego stołu.

Zacząłem się zastanawiać, czy siedzenie na podłodze może być jednym z czynników wpływających na ich zdrowie i długowieczność oraz czy mógłbym wprowadzić ten zwyczaj do własnego życia.

Za każdym razem, gdy siadasz na podłodze i z niej wstajesz, twoje ciało musi wykonać określony ruch. W pewnym sensie przypomina to zrobienie przysiadu, a przysiady są bardzo korzystne dla ciała. Ponadto siedzenie w pozycji podobnej do medytacyjnej zachęca nas do utrzymywania lepszej postawy.

Ponieważ od dawna praktykowałem medytację i miałem już poduszkę do medytacji, postanowiłem przeprowadzić eksperyment: zastąpiłem nią krzesło biurowe, którego używałem do pracy.

Zmodyfikowałem biurko tak, by jego wysokość nadawała się do pracy na siedząco na podłodze, i rozpocząłem eksperyment.

Pierwszy miesiąc

Pierwszy miesiąc był znacznie trudniejszy, niż się spodziewałem. Już po kilku dniach byłem bliski rezygnacji. Bolały mnie kolana i plecy, a mimo doświadczenia w medytacji nie czułem się komfortowo, siedząc na podłodze przez tak długi czas.

Szybko stało się jasne, że siedzenie na podłodze przez osiem godzin dziennie to coś zupełnie innego niż trzydziestominutowa medytacja.

Mimo początkowych trudności postanowiłem kontynuować eksperyment i dać organizmowi wystarczająco dużo czasu na przystosowanie się.

Po pierwszym miesiącu ból kolan i pleców zniknął, a ja zacząłem czuć się znacznie wygodniej. Zauważyłem również niewielką poprawę postawy.

Dwa lata później nadal pracuję na podłodze

Od rozpoczęcia tego eksperymentu minęły już dwa lata i nie zamierzam wracać do siedzenia na krześle biurowym. Czuję się znacznie lepiej niż wcześniej, moja postawa wyraźnie się poprawiła i nie potrafię już sobie wyobrazić spędzania wielu godzin na wygodnym krześle biurowym — które, o ironio, wcale nie wydaje mi się już wygodne.

Odkryłem również, że siedzenie na podłodze pozwala przyjmować wiele różnych pozycji, co także może mieć pozytywny wpływ na ciało. Spędzanie całego dnia w jednej pozycji jest bardzo niezdrowe.

Pomocna może być tutaj joga. Wiele asan da się dostosować do siedzenia i pracy przy komputerze, dzięki czemu możemy regularnie zmieniać pozycję, w której pracujemy.

Co sądzisz o takim miejscu pracy? Czy rozważyłbyś zastąpienie krzesła stanowiskiem na podłodze? A może masz własny nietypowy sposób pracy przy komputerze, dzięki któremu czujesz się wygodniej albo pozostajesz w ruchu?

Artykuł pierwotnie opublikowany po angielsku na CoderLegion.

Dopóki nie zaimplementujesz go po raz piąty.

Rejestracja, logowanie, sesje, weryfikacja adresu e-mail, resetowanie i zmiana hasła, usuwanie konta, role, uprawnienia — żadna z tych funkcji nie jest szczególnie nietypowa. Niemal każda aplikacja potrzebuje jednak jakiejś ich kombinacji, a implementacja często staje się ściśle powiązana z frameworkiem, ORM-em lub infrastrukturą, których akurat użyto w projekcie.

Właśnie ten problem skłonił mnie do zbudowania UserHarbor.

UserHarbor to niezależna od frameworka biblioteka Pythona do zarządzania kontami użytkowników. Jej celem nie jest stworzenie kolejnego frameworka webowego ani kompletnej platformy tożsamości. Zamiast tego udostępnia niewielkie API na poziomie domeny dla typowych operacji na kontach, pozostawiając obsługę HTTP, baz danych i wysyłkę wiadomości e-mail osobnym integracjom.

Odkąd po raz pierwszy napisałem o tym projekcie, coraz ciekawsza staje się dla mnie nie tylko sama warstwa uwierzytelniania, lecz przede wszystkim granica pomiędzy rdzeniem a jego integracjami.

Ten artykuł rozwija moje pierwotne wprowadzenie do UserHarbor i skupia się na tym, jak zmieniała się architektura wraz z rozwojem projektu.

Problem, który chciałem rozwiązać

Wyobraźmy sobie budowę dwóch aplikacji.

Pierwsza korzysta z:

• FastAPI
• SQLAlchemy
• PostgreSQL
• SMTP

Druga korzysta z:

• Flaska
• MongoDB
• zewnętrznego API do wysyłania wiadomości e-mail

Reguły zarządzania użytkownikami są w większości takie same.

Hasło nadal trzeba zweryfikować i zahaszować. Token weryfikacyjny nadal musi wygasnąć. Tokeny resetowania hasła nadal wymagają ochrony. Sesje trzeba tworzyć i unieważniać. Role i uprawnienia trzeba sprawdzać.

W wielu bibliotekach reguły te są jednak wymieszane z modelami bazy danych, handlerami HTTP albo abstrakcjami właściwymi dla konkretnego frameworka.

Chciałem czegoś przeciwnego.

Rdzeń powinien wiedzieć, co powinno się wydarzyć, ale niekoniecznie w jaki sposób aplikacja przechowuje lub przesyła dane.

Prowadzi to do architektury wyglądającej mniej więcej tak:

Aplikacja / framework
        │
        ▼
    UserHarbor
        │
        ├── UserStore
        │       └── baza danych / ORM / własny backend
        │
        └── EmailSender
                └── SMTP / API / własny dostawca

Rdzeń odpowiada za rejestrację, walidację, haszowanie haseł, generowanie i haszowanie tokenów, obsługę sesji oraz reguły autoryzacji.

Adaptery odpowiadają za infrastrukturę.

Niewielkie API na poziomie domeny

UserHarbor obsługuje obecnie typowy cykl życia konta:

• rejestrację użytkownika
• weryfikację adresu e-mail
• logowanie
• sesje
• wylogowanie z jednej lub wszystkich sesji
• zmianę hasła
• reset hasła
• usunięcie konta
• role i uprawnienia

Celowo nie udostępnia własnych endpointów HTTP.

Dzięki temu kod korzystający z rdzenia może wyglądać następująco:

user = harbor.register(
    username="jane",
    email="*Emails are not allowed*",
    password="StrongPassword123!",
)

harbor.verify_email(verification_token)

session_token = harbor.login(
    username="jane",
    password="StrongPassword123!",
)

current_user = harbor.get_current_user(session_token)

Tej samej instancji UserHarbor można używać w FastAPI, Flasku, Django, aplikacji CLI albo w programie, który w ogóle nie udostępnia HTTP.

Autoryzacja działa według tej samej zasady:

harbor.roles.create("admin")
harbor.permissions.create("users.delete")

harbor.roles.grant_permission(
    "admin",
    "users.delete",
)

harbor.grant_role("jane", "admin")

if harbor.has_permission(session_token, "users.delete"):
    delete_user()

Jeśli natomiast dostęp ma zostać wymuszony:

user = harbor.require_permission(
    session_token,
    "users.delete",
)

UserHarbor implementuje prostą kontrolę dostępu opartą na rolach, ale pozostawia politykę autoryzacji właściwą dla aplikacji poza rdzeniem. Celowo nie próbuje stać się uniwersalnym silnikiem polityk.

Niezależność od frameworka nie oznacza nieprzyjazności wobec frameworków

Chciałem uniknąć sytuacji, w której niezależność od frameworka odbywa się kosztem wygody programisty.

Dlatego istnieje między innymi oficjalna integracja userharbor-fastapi.

Zamiast ręcznie pisać trasy uwierzytelniania i zależności, aplikacja FastAPI może skonfigurować UserHarbor i dołączyć adapter:

from fastapi import FastAPI
from userharbor import UserHarbor
from userharbor_fastapi import UserHarborFastAPI

harbor = UserHarbor(
    secret_key="your-secret-key",
    store=store,
    email_sender=email_sender,
)

auth = UserHarborFastAPI(harbor)

app = FastAPI()
app.include_router(
    auth.router,
    prefix="/auth",
    tags=["auth"],
)

Adapter dostarcza warstwę specyficzną dla frameworka: routery, schematy żądań, zależności uwierzytelniania bearer, mapowanie błędów oraz funkcje pomocnicze do wymagania określonych ról lub uprawnień.

Najważniejsze jest to, że FastAPI nadal nie przenika do rdzenia UserHarbor.

Możesz zmienić framework webowy bez zmiany logiki zarządzania kontami.

Trudniejszy problem: co znaczy zaimplementować UserStore?

Początkowo oddzielenie mechanizmu persystencji za interfejsem UserStore wydawało się oczywistym rozwiązaniem.

Definiujemy interfejs i implementujemy jego metody, dzięki czemu SQLAlchemy, MongoDB, Redis czy dowolne inne rozwiązanie może dostarczać warstwę przechowywania danych.

Istnieje jednak subtelny problem.

Zgodność sygnatur metod nie oznacza, że dwie implementacje warstwy danych zachowują się tak samo.

Weźmy pod uwagę token resetowania hasła.

Czy utworzenie nowego tokenu powinno usunąć poprzedni?

Co dzieje się po usunięciu użytkownika?

Czy jego sesje powinny zniknąć automatycznie?

Co powinno się stać, jeśli transakcja nie powiedzie się w połowie zmiany hasła?

Czy próba usunięcia czegoś, co już nie istnieje, powinna zgłosić błąd?

Te zachowania są częścią kontraktu warstwy danych, choć system typów Pythona nie potrafi ich wyrazić.

Stało się to jedną z najważniejszych zmian w UserHarbor 0.7.0.

Zamiana kontraktu adaptera w wykonywalne testy

UserHarbor zawiera teraz zestaw testów kontraktowych wielokrotnego użytku dla implementacji UserStore.

Adapter może zaimportować cały zestaw:

# tests/test_user_store_contract.py

from userharbor.testing.user_store_contract import *

Musi jedynie dostarczyć czystą instancję warstwy danych:

import pytest


@pytest.fixture
def user_store():
    store = create_user_store()

    try:
        yield store
    finally:
        dispose_user_store(store)

Te same testy można następnie uruchamiać dla SQLAlchemy, implementacji przechowującej dane w pamięci lub zupełnie innego backendu persystencji.

Wersja 0.7.0 wprowadziła 57 testów kontraktowych wielokrotnego użytku, obejmujących użytkowników, hasze haseł, tokeny weryfikacji i resetu hasła, sesje, role, uprawnienia, relacje oraz zachowanie transakcji.

Zmienia to znaczenie adaptera.

Zgodny UserStore nie tylko deklaruje implementację interfejsu. Może wykazać, że przestrzega semantyki zachowań oczekiwanej przez rdzeń.

Kontrakt określa na przykład, że:

• nazwy użytkowników i adresy e-mail są unikalne
• utworzenie użytkownika i początkowego tokenu weryfikacyjnego jest atomowe
• nowy token weryfikacyjny zastępuje poprzedni
• nowy token resetowania hasła zastępuje poprzedni
• usunięcie użytkownika usuwa jego sesje i powiązane tokeny
• wielokrotne przypisanie tej samej relacji jest idempotentne
• usunięcie ról i uprawnień usuwa także ich przypisania
• pomyślne transakcje są zatwierdzane
• nieudane transakcje są wycofywane
• zagnieżdżone transakcje uczestniczą w transakcji zewnętrznej

Podczas implementowania kolejnego backendu łatwo przeoczyć te szczegóły. To właśnie takie różnice mogą powodować błędy uwierzytelniania, które ujawniają się dopiero znacznie później.

Dla mnie był to ważny krok w rozwoju architektury: abstrakcję opisują teraz nie tylko protokoły Pythona i dokumentacja, lecz również wykonywalne zachowanie.

Szablon do budowania nowych adapterów warstwy danych

Aby uprościć ten proces, stworzyłem także userharbor-inmemory.

Jest to minimalna implementacja UserStore, która przechowuje dane w pamięci i przechodzi cały kontrakt warstwy danych.

Pełni dwie funkcje.

Po pierwsze, przydaje się w testach i przykładach, które nie wymagają prawdziwej bazy danych.

Po drugie, samo repozytorium może służyć jako szablon do tworzenia nowych integracji warstwy danych. Programista może zacząć od działającej implementacji i przechodzących testów kontraktowych, stopniowo zastępować backend in-memory, a przy tym stale sprawdzać, czy nowy adapter nadal zachowuje się poprawnie.

Chodzi o to, by tworzenie przyszłego adaptera bazy danych sprowadzało się przede wszystkim do następującego procesu:

działający szablon UserStore
        │
        ▼
zastąpienie implementacji persystencji
        │
        ▼
uruchomienie wspólnych testów kontraktowych
        │
        ▼
dodanie testów specyficznych dla backendu

zamiast odtwarzania oczekiwanego zachowania na podstawie implementacji rdzenia.

Zachowanie związane z bezpieczeństwem pozostaje w rdzeniu

Kolejną ważną granicą architektury jest to, że adaptery warstwy danych nigdy nie otrzymują surowych tokenów do zapisania.

UserHarbor generuje surowe tokeny weryfikacyjne, resetowania hasła i sesji, ale haszuje je przed przekazaniem do UserStore.

Surowy token trafia wyłącznie do tej części aplikacji, która go potrzebuje — na przykład do mechanizmu wysyłania e-maili albo do użytkownika po zalogowaniu.

Baza danych przechowuje hasz.

Rdzeń odpowiada także za zachowania takie jak wygasanie tokenów i walidacja sesji.

Operacje, które mogłyby ujawniać istnienie konta, w odpowiednich miejscach zwracają neutralne odpowiedzi. Przykładowo prośba o reset hasła dla nieznanego adresu e-mail nie zdradza, czy konto o takim adresie istnieje.

Istnieją też powiadomienia o zdarzeniach w cyklu życia konta, takich jak:

• udana weryfikacja adresu e-mail
• zmiana hasła
• reset hasła
• usunięcie konta

Interfejs EmailSender decyduje, w jaki sposób wiadomości zostaną dostarczone, ale nie rozstrzyga, kiedy dana operacja jest prawidłowa. Ta decyzja pozostaje w rdzeniu.

SQLAlchemy bez przejmowania kontroli nad aplikacją

Oficjalny adapter SQLAlchemy jest gotowy do użycia, lecz jednym z wymagań projektowych było to, by wdrożenie UserHarbor nie zmuszało aplikacji do przyjęcia całkowicie osobnego modelu użytkownika.

Domyślnie adapter może zarządzać własną tabelą użytkowników.

Aplikacje, które mają już model SQLAlchemy, mogą jednak przekazać go adapterowi:

store = SQLAlchemyUserStore(
    SessionLocal,
    user_model=AppUser,
)

Aplikacja może również mapować swój model na bogatszy publiczny obiekt użytkownika, zamiast ograniczać się do minimalnej reprezentacji UserHarbor.

Dokumentacja opisuje teraz także użycie adaptera z migracjami Alembic zamiast polegania na metadata.create_all() podczas uruchamiania aplikacji.

To rozróżnienie ma znaczenie: przykłady powinny być łatwe do uruchomienia, ale prawdziwe aplikacje potrzebują rozsądnego sposobu zarządzania zmianami schematu.

Instalacja

Sam rdzeń można zainstalować następująco:

pip install userharbor

Można też dołączyć wybrane oficjalne integracje:

pip install "userharbor[sqlalchemy,smtp,fastapi]"

Aby przetestować kompletny oficjalny zestaw:

pip install "userharbor[all]"

Główne oficjalne integracje obejmują obecnie warstwę danych SQLAlchemy, wysyłkę wiadomości przez SMTP oraz obsługę FastAPI.

Czym UserHarbor celowo nie powinien się stać

Niekontrolowane rozrastanie się zakresu funkcji to łatwa pułapka w tego rodzaju projekcie.

Gdy mamy już uwierzytelnianie, kusi nas dodanie OAuth. Następnie logowania społecznościowego. Potem MFA, organizacji, zespołów, list ACL, własności zasobów, paneli administracyjnych i języka polityk.

W końcu „mała biblioteka uwierzytelniania” staje się frameworkiem aplikacyjnym.

Właśnie tego staram się uniknąć.

Rdzeń powinien pozostać skoncentrowany na typowych, podstawowych operacjach zarządzania kontami.

Bardziej wyspecjalizowane funkcje mogą powstawać jako integracje lub osobne biblioteki, jeśli pojawi się na nie zapotrzebowanie. Nie powinny jednak komplikować podstawowego pakietu wszystkim jego użytkownikom.

Jedna z zasad projektowych UserHarbor jest więc celowo nudna:

stabilność jest ważniejsza niż liczba funkcji.

Gdy publiczne API się ustabilizuje, wolę przeznaczać czas na bezpieczeństwo, niezawodność, zgodność i wydajność niż nieustannie poszerzać zakres rdzenia.

Obecny stan

UserHarbor znajduje się obecnie w wersji 0.7.0.

Projekt jest wciąż młody i nie uważam jeszcze ani jego API za stabilne, ani samej biblioteki za gotową do zastosowań produkcyjnych.

Na tym etapie projekt służy w równym stopniu sprawdzaniu architektury, co dodawaniu funkcji.

Szczególnie zależy mi na opinii dotyczącej:

• granicy pomiędzy rdzeniem a integracjami
• kontraktu UserStore
• podejścia opartego na testach kontraktowych
• integracji z FastAPI
• własnych backendów warstwy danych
• kształtu publicznego API
• tego, co powinno — a co nie powinno — należeć do rdzenia

W Pythonie istnieje wiele dobrych bibliotek uwierzytelniania przeznaczonych dla konkretnych frameworków.

UserHarbor bada nieco inne pytanie:

Czy sama domena zarządzania kontami może być wielokrotnie wykorzystywana z różnymi frameworkami i infrastrukturą, podczas gdy integracje pozostają małe, wymienne i niezależnie testowalne?

Jak dotąd uważam, że właśnie ta granica okazuje się najciekawszą częścią projektu.

Linki

Dokumentacja:
https://userharbor.github.io/userharbor/

Repozytorium:
https://github.com/userharbor/userharbor

Integracja FastAPI:
https://github.com/userharbor/userharbor-fastapi

Adapter SQLAlchemy:
https://github.com/userharbor/userharbor-sqlalchemy

Adapter SMTP:
https://github.com/userharbor/userharbor-smtp

Artykuł pierwotnie opublikowany po angielsku na CoderLegion.

• rejestrację
• logowanie
• sesje
• weryfikację adresu e-mail
• reset hasła
• zmianę hasła
• usuwanie konta
• podstawowe role i uprawnienia

Żadna z tych rzeczy nie była szczególnie trudna.

Była za to powtarzalna.

Pisałem już wcześniej podobny kod i nie chciałem w każdym nowym projekcie w Pythonie odtwarzać od podstaw tej samej warstwy zarządzania użytkownikami.

Zacząłem więc pracować nad UserHarbor.

Czym jest UserHarbor?

UserHarbor to niezależna od frameworka biblioteka Pythona służąca do zarządzania kontami użytkowników.

Założenie jest proste:

rdzeń powinien pozostać mały, przewidywalny i niezależny od konkretnego frameworka webowego, bazy danych, ORM-u czy dostawcy poczty.

Rdzeń obsługuje logikę zarządzania kontami. Integracjami zajmują się osobne pakiety adapterów.

Zamiast tworzyć rozwiązanie wyłącznie dla FastAPI, Flaska, Django czy jednego konkretnego stosu technologicznego, chciałem zbudować rdzeń nadający się do użycia w różnych rodzajach aplikacji w Pythonie.

Na przykład w:

• aplikacjach FastAPI
• aplikacjach Flask
• aplikacjach Django
• narzędziach CLI
• narzędziach wewnętrznych
• własnych usługach w Pythonie

Dlaczego nie użyć po prostu biblioteki dla konkretnego frameworka?

Istnieją już dobre narzędzia przeznaczone dla konkretnych frameworków.

Mnie jednak zależało na czymś nieco innym.

Nie chciałem, aby logika zarządzania użytkownikami była ściśle powiązana z:

• frameworkiem webowym
• warstwą bazy danych
• dostawcą poczty
• konkretnym modelem żądań i odpowiedzi

Zamiast tego UserHarbor używa niewielkich interfejsów dla takich elementów jak przechowywanie danych i wysyłanie wiadomości e-mail.

Główne interfejsy to:

class UserStore:
    ...

class EmailSender:
    ...

Rdzenia nie interesuje, w jaki sposób użytkownicy są przechowywani ani jak wysyłane są wiadomości e-mail.

Za tę część odpowiadają adaptery.

Instalacja

Jeśli chcesz dostarczyć własne implementacje UserStore i EmailSender, zainstaluj tylko pakiet rdzenia:

pip install userharbor

Aby zainstalować rdzeń wraz z oficjalnymi adapterami SQLAlchemy, SMTP i FastAPI:

pip install "userharbor[sqlalchemy,smtp,fastapi]"

Możesz też od razu zainstalować wszystkie oficjalne integracje:

pip install "userharbor[all]"

Oficjalne adaptery

Obecnie dostępnych jest kilka oficjalnych pakietów adapterów:

• userharbor-sqlalchemy — przechowywanie danych za pomocą SQLAlchemy
• userharbor-smtp — wysyłanie wiadomości e-mail przez SMTP
• userharbor-fastapi — integracja z FastAPI

Dzięki temu rdzeń pozostaje mały, a jednocześnie typową konfigurację można łatwo zainstalować i uruchomić.

Szybki przykład

Oto dłuższy przykład wykorzystujący SQLAlchemy do przechowywania danych i SMTP do wysyłania wiadomości e-mail:

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

from userharbor import UserHarbor
from userharbor_sqlalchemy import SQLAlchemyUserStore
from userharbor_smtp import SMTPEmailSender

engine = create_engine("sqlite:///users.db")
SessionLocal = sessionmaker(bind=engine)

store = SQLAlchemyUserStore(SessionLocal)
store.metadata.create_all(engine)

email_sender = SMTPEmailSender(
    host="smtp.example.com",
    port=587,
    username="smtp-user",
    password="smtp-password",
    from_email="noreply@example.com",
)

harbor = UserHarbor(
    secret_key="your-secret-key",
    store=store,
    email_sender=email_sender,
)

# Rejestracja użytkownika
harbor.register(
    username="jane",
    email="jane@example.com",
    password="StrongPassword123!",
)

# Weryfikacja adresu e-mail
harbor.verify_email("verification-token-from-email")

# Logowanie
session_token = harbor.login(
    username="jane",
    password="StrongPassword123!",
)

# Weryfikacja sesji
if harbor.verify_session(session_token):
    print("Użytkownik jest zalogowany")

# Pobranie bieżącego użytkownika
current_user = harbor.get_current_user(session_token)
print(current_user.username)

# Utworzenie ról i uprawnień
harbor.roles.create("admin")
harbor.permissions.create("users.delete")

harbor.roles.grant_permission("admin", "users.delete")
harbor.grant_role("jane", "admin")

# Sprawdzenie dostępu
if harbor.has_permission(session_token, "users.delete"):
    print("Użytkownik może usuwać innych użytkowników")

current_admin = harbor.require_role(session_token, "admin")
print(current_admin.username)

# Wylogowanie
harbor.logout(session_token)

# Zmiana hasła
session_token = harbor.login(
    username="jane",
    password="StrongPassword123!",
)

harbor.change_password(
    old_password="StrongPassword123!",
    new_password="EvenStrongerPassword123!",
    session_token=session_token,
)

# Wysłanie wiadomości umożliwiającej zresetowanie hasła
harbor.send_password_reset("jane@example.com")

# Reset hasła
harbor.reset_password(
    new_password="NewStrongPassword123!",
    reset_token="reset-token-from-email",
)

# Usunięcie konta
session_token = harbor.login(
    username="jane",
    password="NewStrongPassword123!",
)

harbor.delete_account(
    password="NewStrongPassword123!",
    session_token=session_token,
)

Pełny przykład FastAPI z oficjalnymi integracjami

Jeśli chcesz wypróbować pełną konfigurację z FastAPI, SQLAlchemy i SMTP, zainstaluj wszystkie oficjalne integracje:

pip install "userharbor[all]"

Następnie utwórz aplikację FastAPI:

import os

from fastapi import FastAPI
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

from userharbor import UserHarbor
from userharbor_fastapi import UserHarborFastAPI
from userharbor_smtp import SMTPEmailSender
from userharbor_sqlalchemy import SQLAlchemyUserStore

engine = create_engine("sqlite:///users.db")
SessionLocal = sessionmaker(bind=engine)

store = SQLAlchemyUserStore(SessionLocal)
store.metadata.create_all(engine)

email_sender = SMTPEmailSender(
    host=os.getenv("HOST", "smtp.example.com"),
    port=int(os.getenv("PORT", 587)),
    username=os.getenv("USERNAME"),
    password=os.getenv("PASSWORD"),
    from_email=os.getenv("USERNAME", ""),
)

harbor = UserHarbor(
    secret_key="your-secret-key",
    store=store,
    email_sender=email_sender,
)

auth = UserHarborFastAPI(harbor)

app = FastAPI()

app.include_router(auth.router, prefix="/auth", tags=["auth"])

if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8000)

Zasady projektowe

Projekt opiera się na kilku założeniach.

Rdzeń powinien pozostać mały

UserHarbor nie ma stać się kompletną platformą do zarządzania tożsamością.

Rdzeń koncentruje się na podstawowych procesach związanych z zarządzaniem kontami:

• rejestracji
• logowaniu
• sesjach
• weryfikacji adresu e-mail
• resetowaniu hasła
• zmianie hasła
• usuwaniu konta
• prostej kontroli dostępu opartej na rolach

Wszystko, co jest wysoce specyficzne dla danej aplikacji, powinno pozostać poza rdzeniem.

Adaptery powinny znajdować się poza rdzeniem

Integracje z bazami danych, ORM-ami, pocztą i frameworkami powinny być osobnymi pakietami.

Dzięki temu rdzeń pozostaje niezależny, a inni mogą łatwiej tworzyć własne integracje.

Ktoś mógłby na przykład stworzyć:

• userharbor-redis
• userharbor-mongodb
• userharbor-sendgrid
• userharbor-resend
• userharbor-django
• userharbor-flask

bez modyfikowania głównego pakietu.

API powinno być nudne

Staram się, aby publiczne API było jawne i przewidywalne.

Bez ukrytej magii frameworka. Bez narzuconego modelu bazy danych. Bez zależności od jednego konkretnego sposobu budowania aplikacji w Pythonie.

Obecny stan

Projekt jest nadal na wczesnym etapie rozwoju.

Podstawowe procesy działają, ale API nie jest jeszcze w pełni stabilne. Obecnie nie nazwałbym tej biblioteki gotową do zastosowań produkcyjnych.

W tej chwili zależy mi przede wszystkim na opiniach dotyczących:

• publicznego API
• architektury adapterów
• granicy pomiędzy rdzeniem a integracjami
• integracji z SQLAlchemy
• integracji z FastAPI
• tego, czy prosty RBAC powinien należeć do rdzenia
• tego, jak powinno wyglądać wygodne tworzenie własnych adapterów

Linki

Dokumentacja:
https://userharbor.github.io/userharbor/

Repozytorium:
https://github.com/userharbor/userharbor

Integracja FastAPI:
https://github.com/userharbor/userharbor-fastapi

Adapter SQLAlchemy:
https://github.com/userharbor/userharbor-sqlalchemy

Adapter SMTP:
https://github.com/userharbor/userharbor-smtp

Opinie mile widziane

Będę wdzięczny za wszelkie uwagi, zwłaszcza od osób, które wielokrotnie tworzyły w Pythonie mechanizmy zarządzania użytkownikami.

Czy takie podejście oparte na adapterach ma sens?

Czy spodziewalibyście się prostych ról i uprawnień w rdzeniu, czy raczej w osobnym pakiecie?

A gdybyście integrowali UserHarbor z własnym projektem, jakiego API byście oczekiwali?

Aktualizacja: później napisałem bardziej szczegółowy artykuł o architekturze adapterów UserHarbor i wykonywalnym kontrakcie warstwy danych.

Artykuł pierwotnie opublikowany po angielsku na DEV Community.