Documentation
¶
Index ¶
- Constants
- Variables
- func RenderConfigDump(d ConfigDump) string
- func WritePidFile(path string) (func(), error)
- type ConfigDump
- type ConfigEntry
- type DumpedRoute
- type DumpedRoutes
- type EmbedDeps
- type FeedNoteLister
- type FeedUserResolver
- type Server
- func (s *Server) APIDoc(c echo.Context) error
- func (s *Server) DumpRoutes(w io.Writer) error
- func (s *Server) Handler() http.Handler
- func (s *Server) OpenAPISpec(c echo.Context) error
- func (s *Server) ServeHandler() http.Handler
- func (s *Server) SetSyncDeliverHookForTest(fn func(payload queue.DeliverPayload) error)
- func (s *Server) Shutdown(ctx context.Context) error
- func (s *Server) StartBackground() error
- func (s *Server) StartBackgroundForTest() error
- func (s *Server) StopBackground(ctx context.Context) error
- type StartReport
- type StopReport
- type Supervisor
- type SupervisorDeps
Constants ¶
const ( // CSPModeOff sends no header. 既定。 CSPModeOff = "off" // CSPModeReportOnly sends `Content-Security-Policy-Report-Only`, which // never blocks anything and only reports violations. CSPModeReportOnly = "report-only" // CSPModeEnforce sends `Content-Security-Policy`. CSPModeEnforce = "enforce" )
CSP modes accepted by the `frontendContentSecurityPolicy` config key.
const CSPReportPath = "/csp-report"
CSPReportPath is where browsers post violation reports.
`/api` 配下に置かない。あちらは auth / body limit / rate limit の既定が API 用に組んであり、認証不要で外から叩かれるこの endpoint とは要件が違う。
Variables ¶
var ErrAlreadyRunning = errors.New("server: another instance appears to be running")
ErrAlreadyRunning is returned by WritePidFile when the existing PID file names a process that is still alive — likely another mk instance.
Functions ¶
func RenderConfigDump ¶
func RenderConfigDump(d ConfigDump) string
RenderConfigDump formats the dump for a terminal.
func WritePidFile ¶
WritePidFile writes the current PID to path. If path is empty it returns a no-op cleanup function and nil error — pidFile is an opt-in feature.
Returns a cleanup function that removes the file (best effort) on shutdown. When path is empty the cleanup function is a no-op, so callers can defer it unconditionally.
既存 PID ファイルが live なプロセスを指しているときは ErrAlreadyRunning を返して起動を拒否する。stale なファイル (PID は dead) なら上書きする (#497)。
Types ¶
type ConfigDump ¶
type ConfigDump struct {
// Settings are resolved config values (YAML + MK_* env + defaults).
Settings []ConfigEntry `json:"settings"`
// Effective are values derived from the settings that the operator
// cannot read off the config file.
Effective []ConfigEntry `json:"effective"`
// Warnings call out combinations that behave differently than the
// setting names suggest.
Warnings []string `json:"warnings,omitempty"`
}
ConfigDump is the resolved view of an instance's configuration.
**単に設定を再表示するだけなら価値が薄い。** 中心は Effective で、設定値 そのものではないが実際に効く値を出す (#2469)。
func BuildConfigDump ¶
func BuildConfigDump(cfg *config.Config, role config.ProcessRole) ConfigDump
BuildConfigDump assembles the dump for cfg.
**算出は本番と同じ関数を使う。** 実効値のために別実装を起こすと、表示と実際が 食い違ったときにどちらが正しいか分からなくなる。
type ConfigEntry ¶
type ConfigEntry struct {
Key string `json:"key"`
Value string `json:"value"`
// Note explains where the value came from or what it implies.
Note string `json:"note,omitempty"`
}
ConfigEntry is one line of the dump.
type DumpedRoute ¶
DumpedRoute represents a single registered Echo route, used by DumpRoutes to expose mk-go's HTTP surface for tooling (api-compat matrix etc).
type DumpedRoutes ¶
type DumpedRoutes struct {
MisskeyVersion string `json:"misskeyVersion"`
MkGoVersion string `json:"mkGoVersion"`
Routes []DumpedRoute `json:"routes"`
}
DumpedRoutes is the JSON payload emitted by DumpRoutes.
type EmbedDeps ¶
type EmbedDeps struct {
NoteRepo repository.NoteRepository
UserRepo repository.UserRepository
ClipRepo repository.ClipRepository
PackNote func(c echo.Context, note *model.Note) (any, error)
PackUser func(c echo.Context, user *model.User) (any, error)
PackClip func(c echo.Context, clip *model.Clip) (any, error)
}
EmbedDeps carries the repositories and packers the embed pages need.
embed は **認証なしで誰でも読める** 経路なので、pack は viewer なし (viewerID = "") で行う。viewer を渡してしまうと、埋め込み経由で viewer 依存の フィールド (isFollowing 等) が漏れる。
type FeedNoteLister ¶
type FeedNoteLister interface {
ListPublicNotesForFeed(userID string, limit int) ([]*model.Note, error)
}
FeedNoteLister returns the notes a user's feed should contain.
type FeedUserResolver ¶
FeedUserResolver resolves a local user by its username.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server represents the HTTP server.
func New ¶
New creates a new Server. Returns an error when the queue driver fails to initialise (e.g. mkq driver failing to PING Redis at startup).
func (*Server) APIDoc ¶
APIDoc serves /api-doc, the API reference page that renders /api.json.
CSPはfrontendと同じ設定(frontendContentSecurityPolicy)に従い、script-srcに Scalarのファイルだけを足す(版まで含めたURLで、jsdelivrの他のパッケージは 許さない)。他のページのCSPは変えない。styleはScalarが実行時に`<style>`を 差し込むので、frontendの既定のまま'unsafe-inline'で通す。hashを足すと 'unsafe-inline'が無視され、Scalarの差し込むstyleが全部止まる。
func (*Server) DumpRoutes ¶
DumpRoutes writes all registered Echo routes as JSON to w. `elythia dump-routes` から呼ばれ、tools/apicompat が Misskey TS の endpoint 集合 (filename-derived + ApiServerService 直登録) と突き合わせる ための入力になる。echo 内部の "/*" catch-all 等は除外しない (caller 側で 正規化する想定)。出力 path は string sort で安定化。
Phase 2 で TS の api.json ベースに切り替える際もこの method の出力形式は そのまま使える想定 (input source 側だけ差し替え)。
func (*Server) Handler ¶
Handler returns the underlying http.Handler for use with httptest. E2Eテスト等でサーバーを外部から起動する場合に使う���
func (*Server) OpenAPISpec ¶
OpenAPISpec serves /api.json.
本家のgen-spec.tsと同じ形で、本家互換のエンドポイントには引数・応答・エラーの 例を付ける(internal/api/openapi、#3810)。載せるのはEchoに登録したルートに あるエンドポイントとメソッドだけにする。本家にあってもElythiaが持たない ものは載らず、Elythia独自のものは型を付けずに別のタグで一覧だけ載せる。
ルートは組み立ての後に変わらないので、文書は初回に1度だけ作る。本文は約1.3MB あり、全体のgzip middlewareに任せるとリクエストのたびに圧縮し直す(認証なしで 叩ける)。gzipした本文も1度だけ作り、ここでContent-Encodingを決める (selfEncodedRoutes。/api/emojisと同じ書き方)。
func (*Server) ServeHandler ¶
ServeHandler returns the handler the listener should serve for this process role: the full router for a node that runs the server, or the minimal /healthz (+ /metrics) mux for a queue-only node.
func (*Server) SetSyncDeliverHookForTest ¶
func (s *Server) SetSyncDeliverHookForTest(fn func(payload queue.DeliverPayload) error)
SetSyncDeliverHookForTest replaces the queued deliver enqueue with the supplied synchronous hook. e2e_federation 系テストで queue worker 経由の deliver が動かない/動かしたくないシナリオで、sign + HTTP POST を inline で実行する用途。fn=nil で本番経路 (queue) に戻る。
production code から呼ばないこと (#780)。
func (*Server) Shutdown ¶
Shutdown stops this server generation: streaming connections, the queue worker and every background service such as the chart management loop. It is the same as StopBackground and safe to call more than once.
func (*Server) StartBackground ¶
StartBackground launches the background work of this server generation, in this order: the named parts of the lifecycle list in list order (#3703), the queue worker, auto-scale and scheduler (when the process role runs the queue) and the chart save loop. It does not listen; the Supervisor owns the listener and routes requests to Handler / ServeHandler.
Only the first call of StartBackground or StartBackgroundForTest starts anything; later calls of either return its result. When it returns an error, the caller stops the generation with StopBackground, which also stops the parts that did not start. Once StopBackground has begun (or the construction failed), it starts nothing and returns errGenerationStopped; a start that is running when StopBackground begins finishes first, and StopBackground then stops what it started (#3709).
listener を Server から外したのは、メンテナンスで Server を作り直しても listener を張ったままにするため (#3463)。
func (*Server) StartBackgroundForTest ¶
StartBackgroundForTest starts the named parts of the generation, the queue worker and the optional auto-scale and scheduler, without launching the HTTP listener. Unlike StartBackground it does not look at the process role and does not start the chart management.
It goes through the same once as StartBackground (#3709): only the first call of either starts anything, and later calls of either return the result of the first. Once StopBackground has begun, it starts nothing and returns errGenerationStopped.
StopBackground stops the queue worker, auto-scale and scheduler it started whatever the process role (#3713), as it does for StartBackground.
用途: e2e_federation 系のテストで `httptest.Server` 経由で echo handler を 外部 listener にぶら下げつつ、deliver / inbox 処理など async queue 経路も 動かしたい場合 (#435)。本番経路 (Server.Start) は HTTP listener を含めて すべて起動するが、テストでは echo を test 側が制御するためここから queue 部分だけ抽出する。
production code から呼ばないこと。
func (*Server) StopBackground ¶
StopBackground stops everything StartBackground and the constructor started, closes the streaming connections with a 1012 close frame and closes this generation's Redis subscriptions. It does not close the DB pool or the Redis clients, which the caller owns. Only the first call does the work; later calls return its result.
It first marks the generation stopped, after a start that is running has finished; StartBackground and StartBackgroundForTest called after that start nothing and return errGenerationStopped (#3709).
The stop runs the named steps of shutdownSteps in order. When a step panics, the panic is logged and the later steps still run (#3711); when the stop of a part of the lifecycle list panics, the panic is logged and the rest of the list still stops (#3707). The errors of the stop are one error per panicked step (wrapping errShutdownStep and naming the step), the error of the lifecycle list (one error per panicked part, wrapping errLifecycleStop) and the error of echo's shutdown. It returns nil when there is none, the error itself when there is exactly one (so a stop without a panic returns echo's error as is), and otherwise their errors.Join in step order (see runShutdownSteps).
type StartReport ¶
type StartReport struct {
OpenDB time.Duration
Construct time.Duration
StartBackground time.Duration
}
StartReport describes how long building and starting a generation took (#3802). A step that did not run is zero.
type StopReport ¶
type StopReport struct {
// InFlight is the number of HTTP requests still running when the drain
// wait gave up.
InFlight int64
// OpenConns is the number of DB connections the pool still held when the
// close wait gave up (0 when the pool closed).
OpenConns int
// Err is the error StopBackground or CloseDB returned.
Err error
// Drain, StopBackground and CloseDB are how long each step took
// (#3802). 作り直す範囲を狭めないと決めた根拠で、本番のログで作り直しが
// 遅くなっていないかを見るため。
Drain time.Duration
StopBackground time.Duration
CloseDB time.Duration
}
StopReport describes how stopping a generation went.
type Supervisor ¶
type Supervisor struct {
// contains filtered or unexported fields
}
Supervisor owns the listener of a serving process and the current server generation, and can stop a generation and build a new one without closing the listener.
listener と Redis のクライアントは Supervisor が世代をまたいで持つ。 Server・DB のプール・Server が持つキャッシュや購読や定期処理は、世代ごとに 作り直す。メンテナンスの間に DB への接続を 0 にし、抜けるときに DB に由来する 状態を全部読み直すため (#3463、設計の方式B)。
func NewSupervisor ¶
func NewSupervisor(cfg *config.Config, redis *cache.RedisClients, deps SupervisorDeps) (*Supervisor, error)
NewSupervisor builds the first server generation (opening the DB pool) and returns a Supervisor ready to Start. When deps.Maintenance reports an active maintenance, it opens nothing and starts with the maintenance handler instead; the generation is built once the maintenance is over.
func (*Supervisor) ServeHTTP ¶
func (s *Supervisor) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP dispatches to the current handler.
func (*Supervisor) Shutdown ¶
func (s *Supervisor) Shutdown(ctx context.Context) error
Shutdown stops the current generation and closes its DB pool, then stops the listener and removes the UNIX socket file. Safe to call more than once.
順序と時間の配分:
- メンテナンスの監視と判定役を止め、新しいリクエストを unavailable へ回す
- 処理中の HTTP リクエストを待つ (WebSocket は数えない)。世代の切り替えが 走っていればその終わりも待つ。どちらも全体の 1/3 まで
- 世代の背景処理を止める (StopBackground: streaming を 1012 で閉じ、queue の 停止・投げっぱなしの goroutine の回収・shutdown hook・chart の保存)。処理中のリクエストの待ちが上限に達しても 呼ぶ。渡す ctx の期限は全体の期限 (切れていればそこから shutdownStopMin)
- 最後に DB を閉じ、メンテナンスの報告を消す。処理中のリクエストが残って いたら、その数をログに出す
例外: 切り替えのロックが 2 の上限までに取れなければ、世代は切り替えの側に任せ、 3 と 4 を行わない。報告は消さず、プロセスが終わるまで書き続ける (切り替えの 途中の世代が DB を開きうるので、判定役に待たせる)。
どの順序でも、メンテナンスの判定は誤らない。判定役は pg_stat_activity を 根拠にし、報告が消えたことを「手放した」とは数えない (#3463 の設計第2版)。
呼び出し元の ctx が切れても、3 を始める (または 3 を行わないと決める) 前には 返らない。その後は ctx が切れた時点で返り、残りは裏で続く。返った後に呼び出し元が プロセスを終えれば、hook は途中で切られうる。
func (*Supervisor) Start ¶
func (s *Supervisor) Start() error
Start starts the background work of the current generation, listens on the configured UNIX socket or TCP port and serves until Shutdown.
type SupervisorDeps ¶
type SupervisorDeps struct {
// OpenDB opens the application DB pool.
OpenDB func(cfg *config.Config) (*gorm.DB, error)
// NewServer builds a server generation on db.
NewServer func(cfg *config.Config, db *gorm.DB, redis *cache.RedisClients) (*Server, error)
// CloseDB closes every pool behind db (primary and replicas).
CloseDB func(db *gorm.DB) error
// PrepareDB, when set, runs on each newly opened database before the
// server generation is built on it (#3909: pg_stat_statements). It must
// not fail the build; it logs instead.
PrepareDB func(db *gorm.DB)
// DrainTimeout bounds the wait for in-flight requests and for the DB pool
// to close when a generation stops. Zero means defaultDrainTimeout.
DrainTimeout time.Duration
// Maintenance, when set, makes the Supervisor follow the maintenance
// state in Redis: it stops the generation when a maintenance starts and
// builds a new one when it ends (#3463).
Maintenance *maintmode.Store
// MaintenanceCounter, when set together with Maintenance, makes the
// Supervisor a candidate judge: it takes the judge lock when nobody
// holds it and decides from pg_stat_activity when the database has been
// let go.
MaintenanceCounter maintmode.Counter
// ProcessID names this process in its maintenance report and as a judge.
ProcessID string
// MaintenancePoll overrides maintmode.PollInterval, and also
// maintmode.IdlePollInterval unless MaintenanceIdlePoll is set (tests).
MaintenancePoll time.Duration
// MaintenanceIdlePoll overrides maintmode.IdlePollInterval (tests).
MaintenanceIdlePoll time.Duration
}
SupervisorDeps are the constructors a Supervisor uses to build and tear down a server generation. Tests replace them.
Source Files
¶
- apidoc.go
- autoscale_wiring.go
- avatar.go
- backup_admin.go
- caches.go
- charts.go
- config_dump.go
- core_parts.go
- csp_report.go
- devmode.go
- drive_lookup_adapter.go
- embed.go
- emoji_redirect.go
- endpoint_catalog.go
- feed.go
- files.go
- frontend.go
- frontend_csp.go
- frontend_static.go
- gzip_media.go
- head_routes.go
- identicon.go
- instance_actor_signer.go
- json_binder.go
- json_serializer.go
- lifecycle.go
- lifecycle_parts.go
- maintenance.go
- metrics_route.go
- oauth_transport.go
- openapi.go
- outbound_http.go
- param_shadow.go
- pidfile.go
- plugin_accounts.go
- plugin_notifications.go
- plugin_peer.go
- plugin_peer_limit.go
- plugin_peer_lookup.go
- plugin_peer_ratelimit.go
- plugin_queue_names.go
- plugin_secrets.go
- plugin_wiring.go
- queue_adapter.go
- queue_factory.go
- queue_only_listener.go
- queue_runtime.go
- reaction_flush_tick.go
- remote_check.go
- role_notif_lookup.go
- route_parts.go
- router.go
- router_adapters.go
- routes_admin.go
- routes_announcements.go
- routes_antennas.go
- routes_auth.go
- routes_channels.go
- routes_charts.go
- routes_chat.go
- routes_clips.go
- routes_drive.go
- routes_emojis.go
- routes_federation.go
- routes_fetch.go
- routes_flash.go
- routes_gallery.go
- routes_games.go
- routes_hashtags.go
- routes_i.go
- routes_meta.go
- routes_notes.go
- routes_notifications.go
- routes_pages.go
- routes_relations.go
- routes_roles.go
- routes_users.go
- search.go
- server.go
- shutdown_steps.go
- ssr_meta.go
- static_asset.go
- twemojibadge.go
- ugc_visibility.go
- url_preview.go
- webresource.go
- wiring.go
- wiring_accounts.go
- wiring_admin.go
- wiring_background_jobs.go
- wiring_cache_invalidation.go
- wiring_check.go
- wiring_core.go
- wiring_fed.go
- wiring_federation_routes.go
- wiring_frontend_routes.go
- wiring_handlers.go
- wiring_queue.go
- wiring_repos.go
- wiring_stream.go
- wiring_streaming.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package paramshadow runs upstream's paramDef validation (internal/api/ paramschema) in front of the API handlers.
|
Package paramshadow runs upstream's paramDef validation (internal/api/ paramschema) in front of the API handlers. |