From babab0bf5e1b6afc1bccf26e5ef0aec69972599e Mon Sep 17 00:00:00 2001 From: techknowlogick Date: Mon, 27 Sep 2021 19:38:06 -0400 Subject: [PATCH] Add nodeinfo endpoint for federation purposes (#16953) Nodeinfo is a way to expose certain metadata about a server for use of discovery regarding functionality of its federation capabilities. Two endpoints are required: 1. `/.well-known/nodeinfo` which informs client where it can find the location of the location of its metadata (including which version of the schema is used) 2. the endpoint which exposes the metadata in json format according to schema. Notes: * `openRegistrations` is a required field, but I propose to set to false as default in case someone writes a crawler to discover "open" gitea instances * to limit data leakage I also propose to not include the `usage` field (note it is required so it should be included, but left as empty). More info: https://github.com/jhass/nodeinfo https://github.com/jhass/nodeinfo/tree/main/schemas/2.1 http://nodeinfo.diaspora.software/protocol.html --- custom/conf/app.example.ini | 9 ++ .../doc/advanced/config-cheat-sheet.en-us.md | 4 + modules/setting/federation.go | 22 +++ modules/setting/setting.go | 1 + modules/structs/nodeinfo.go | 44 ++++++ routers/api/v1/api.go | 3 + routers/api/v1/misc/nodeinfo.go | 45 ++++++ routers/api/v1/swagger/nodeinfo.go | 16 ++ routers/web/nodeinfo.go | 33 ++++ routers/web/web.go | 3 + templates/swagger/v1_json.tmpl | 144 ++++++++++++++++++ 11 files changed, 324 insertions(+) create mode 100644 modules/setting/federation.go create mode 100644 modules/structs/nodeinfo.go create mode 100644 routers/api/v1/misc/nodeinfo.go create mode 100644 routers/api/v1/swagger/nodeinfo.go create mode 100644 routers/web/nodeinfo.go diff --git a/custom/conf/app.example.ini b/custom/conf/app.example.ini index 90a11ec65..f8286a2e8 100644 --- a/custom/conf/app.example.ini +++ b/custom/conf/app.example.ini @@ -2081,6 +2081,15 @@ PATH = ;; Allow private addresses defined by RFC 1918, RFC 1122, RFC 4632 and RFC 4291 (false by default) ;ALLOW_LOCALNETWORKS = false +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;[federation] +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;; +;; Enable/Disable federation capabilities +; ENABLED = true + ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; default storage for attachments, lfs and avatars diff --git a/docs/content/doc/advanced/config-cheat-sheet.en-us.md b/docs/content/doc/advanced/config-cheat-sheet.en-us.md index de9b794db..d80f96b3d 100644 --- a/docs/content/doc/advanced/config-cheat-sheet.en-us.md +++ b/docs/content/doc/advanced/config-cheat-sheet.en-us.md @@ -953,6 +953,10 @@ Task queue configuration has been moved to `queue.task`. However, the below conf - `ALLOW_LOCALNETWORKS`: **false**: Allow private addresses defined by RFC 1918, RFC 1122, RFC 4632 and RFC 4291 - `SKIP_TLS_VERIFY`: **false**: Allow skip tls verify +## Federation (`federation`) + +- `ENABLED`: **true**: Enable/Disable federation capabilities + ## Mirror (`mirror`) - `ENABLED`: **true**: Enables the mirror functionality. Set to **false** to disable all mirrors. diff --git a/modules/setting/federation.go b/modules/setting/federation.go new file mode 100644 index 000000000..c30006078 --- /dev/null +++ b/modules/setting/federation.go @@ -0,0 +1,22 @@ +// Copyright 2021 The Gitea Authors. All rights reserved. +// Use of this source code is governed by a MIT-style +// license that can be found in the LICENSE file. + +package setting + +import "code.gitea.io/gitea/modules/log" + +// Federation settings +var ( + Federation = struct { + Enabled bool + }{ + Enabled: true, + } +) + +func newFederationService() { + if err := Cfg.Section("federation").MapTo(&Federation); err != nil { + log.Fatal("Failed to map Federation settings: %v", err) + } +} diff --git a/modules/setting/setting.go b/modules/setting/setting.go index f00ab242c..afd1e49ae 100644 --- a/modules/setting/setting.go +++ b/modules/setting/setting.go @@ -1188,6 +1188,7 @@ func NewServices() { NewQueueService() newProject() newMimeTypeMap() + newFederationService() } // NewServicesForInstall initializes the services for install diff --git a/modules/structs/nodeinfo.go b/modules/structs/nodeinfo.go new file mode 100644 index 000000000..6fd1eb624 --- /dev/null +++ b/modules/structs/nodeinfo.go @@ -0,0 +1,44 @@ +// Copyright 2021 The Gitea Authors. All rights reserved. +// Use of this source code is governed by a MIT-style +// license that can be found in the LICENSE file. + +package structs + +// NodeInfo contains standardized way of exposing metadata about a server running one of the distributed social networks +type NodeInfo struct { + Version string `json:"version"` + Software NodeInfoSoftware `json:"software"` + Protocols []string `json:"protocols"` + Services NodeInfoServices `json:"services"` + OpenRegistrations bool `json:"openRegistrations"` + Usage NodeInfoUsage `json:"usage"` + Metadata struct{} `json:"metadata"` +} + +// NodeInfoSoftware contains Metadata about server software in use +type NodeInfoSoftware struct { + Name string `json:"name"` + Version string `json:"version"` + Repository string `json:"repository"` + Homepage string `json:"homepage"` +} + +// NodeInfoServices contains the third party sites this server can connect to via their application API +type NodeInfoServices struct { + Inbound []string `json:"inbound"` + Outbound []string `json:"outbound"` +} + +// NodeInfoUsage contains usage statistics for this server +type NodeInfoUsage struct { + Users NodeInfoUsageUsers `json:"users"` + LocalPosts int `json:"localPosts,omitempty"` + LocalComments int `json:"localComments,omitempty"` +} + +// NodeInfoUsageUsers contains statistics about the users of this server +type NodeInfoUsageUsers struct { + Total int `json:"total,omitempty"` + ActiveHalfyear int `json:"activeHalfyear,omitempty"` + ActiveMonth int `json:"activeMonth,omitempty"` +} diff --git a/routers/api/v1/api.go b/routers/api/v1/api.go index 082381d31..0a967e3c5 100644 --- a/routers/api/v1/api.go +++ b/routers/api/v1/api.go @@ -580,6 +580,9 @@ func Routes(sessioner func(http.Handler) http.Handler) *web.Route { }) } m.Get("/version", misc.Version) + if setting.Federation.Enabled { + m.Get("/nodeinfo", misc.NodeInfo) + } m.Get("/signing-key.gpg", misc.SigningKey) m.Post("/markdown", bind(api.MarkdownOption{}), misc.Markdown) m.Post("/markdown/raw", misc.MarkdownRaw) diff --git a/routers/api/v1/misc/nodeinfo.go b/routers/api/v1/misc/nodeinfo.go new file mode 100644 index 000000000..bc36fa1be --- /dev/null +++ b/routers/api/v1/misc/nodeinfo.go @@ -0,0 +1,45 @@ +// Copyright 2021 The Gitea Authors. All rights reserved. +// Use of this source code is governed by a MIT-style +// license that can be found in the LICENSE file. + +package misc + +import ( + "net/http" + + "code.gitea.io/gitea/modules/context" + "code.gitea.io/gitea/modules/setting" + "code.gitea.io/gitea/modules/structs" +) + +// NodeInfo returns the NodeInfo for the Gitea instance to allow for federation +func NodeInfo(ctx *context.APIContext) { + // swagger:operation GET /nodeinfo miscellaneous getNodeInfo + // --- + // summary: Returns the nodeinfo of the Gitea application + // produces: + // - application/json + // responses: + // "200": + // "$ref": "#/responses/NodeInfo" + + nodeInfo := &structs.NodeInfo{ + Version: "2.1", + Software: structs.NodeInfoSoftware{ + Name: "gitea", + Version: setting.AppVer, + Repository: "https://github.com/go-gitea/gitea.git", + Homepage: "https://gitea.io/", + }, + Protocols: []string{"activitypub"}, + Services: structs.NodeInfoServices{ + Inbound: []string{}, + Outbound: []string{}, + }, + OpenRegistrations: setting.Service.ShowRegistrationButton, + Usage: structs.NodeInfoUsage{ + Users: structs.NodeInfoUsageUsers{}, + }, + } + ctx.JSON(http.StatusOK, nodeInfo) +} diff --git a/routers/api/v1/swagger/nodeinfo.go b/routers/api/v1/swagger/nodeinfo.go new file mode 100644 index 000000000..c1ecf3a3f --- /dev/null +++ b/routers/api/v1/swagger/nodeinfo.go @@ -0,0 +1,16 @@ +// Copyright 2021 The Gitea Authors. All rights reserved. +// Use of this source code is governed by a MIT-style +// license that can be found in the LICENSE file. + +package swagger + +import ( + api "code.gitea.io/gitea/modules/structs" +) + +// NodeInfo +// swagger:response NodeInfo +type swaggerResponseNodeInfo struct { + // in:body + Body api.NodeInfo `json:"body"` +} diff --git a/routers/web/nodeinfo.go b/routers/web/nodeinfo.go new file mode 100644 index 000000000..2ee94e35e --- /dev/null +++ b/routers/web/nodeinfo.go @@ -0,0 +1,33 @@ +// Copyright 2021 The Gitea Authors. All rights reserved. +// Use of this source code is governed by a MIT-style +// license that can be found in the LICENSE file. + +package web + +import ( + "fmt" + "net/http" + + "code.gitea.io/gitea/modules/context" + "code.gitea.io/gitea/modules/setting" +) + +type nodeInfoLinks struct { + Links []nodeInfoLink `json:"links"` +} + +type nodeInfoLink struct { + Href string `json:"href"` + Rel string `json:"rel"` +} + +// NodeInfoLinks returns links to the node info endpoint +func NodeInfoLinks(ctx *context.Context) { + nodeinfolinks := &nodeInfoLinks{ + Links: []nodeInfoLink{{ + fmt.Sprintf("%sapi/v1/nodeinfo", setting.AppURL), + "http://nodeinfo.diaspora.software/ns/schema/2.1", + }}, + } + ctx.JSON(http.StatusOK, nodeinfolinks) +} diff --git a/routers/web/web.go b/routers/web/web.go index 8d984abcf..a56a2250b 100644 --- a/routers/web/web.go +++ b/routers/web/web.go @@ -234,6 +234,9 @@ func RegisterRoutes(m *web.Route) { // for health check m.Get("/", Home) m.Get("/.well-known/openid-configuration", user.OIDCWellKnown) + if setting.Federation.Enabled { + m.Get("/.well-known/nodeinfo", NodeInfoLinks) + } m.Group("/explore", func() { m.Get("", func(ctx *context.Context) { ctx.Redirect(setting.AppSubURL + "/explore/repos") diff --git a/templates/swagger/v1_json.tmpl b/templates/swagger/v1_json.tmpl index ef4f9247c..03d1cbda9 100644 --- a/templates/swagger/v1_json.tmpl +++ b/templates/swagger/v1_json.tmpl @@ -615,6 +615,23 @@ } } }, + "/nodeinfo": { + "get": { + "produces": [ + "application/json" + ], + "tags": [ + "miscellaneous" + ], + "summary": "Returns the nodeinfo of the Gitea application", + "operationId": "getNodeInfo", + "responses": { + "200": { + "$ref": "#/responses/NodeInfo" + } + } + } + }, "/notifications": { "get": { "consumes": [ @@ -15560,6 +15577,127 @@ }, "x-go-package": "code.gitea.io/gitea/modules/structs" }, + "NodeInfo": { + "description": "NodeInfo contains standardized way of exposing metadata about a server running one of the distributed social networks", + "type": "object", + "properties": { + "metadata": { + "type": "object", + "x-go-name": "Metadata" + }, + "openRegistrations": { + "type": "boolean", + "x-go-name": "OpenRegistrations" + }, + "protocols": { + "type": "array", + "items": { + "type": "string" + }, + "x-go-name": "Protocols" + }, + "services": { + "$ref": "#/definitions/NodeInfoServices" + }, + "software": { + "$ref": "#/definitions/NodeInfoSoftware" + }, + "usage": { + "$ref": "#/definitions/NodeInfoUsage" + }, + "version": { + "type": "string", + "x-go-name": "Version" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, + "NodeInfoServices": { + "description": "NodeInfoServices contains the third party sites this server can connect to via their application API", + "type": "object", + "properties": { + "inbound": { + "type": "array", + "items": { + "type": "string" + }, + "x-go-name": "Inbound" + }, + "outbound": { + "type": "array", + "items": { + "type": "string" + }, + "x-go-name": "Outbound" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, + "NodeInfoSoftware": { + "description": "NodeInfoSoftware contains Metadata about server software in use", + "type": "object", + "properties": { + "homepage": { + "type": "string", + "x-go-name": "Homepage" + }, + "name": { + "type": "string", + "x-go-name": "Name" + }, + "repository": { + "type": "string", + "x-go-name": "Repository" + }, + "version": { + "type": "string", + "x-go-name": "Version" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, + "NodeInfoUsage": { + "description": "NodeInfoUsage contains usage statistics for this server", + "type": "object", + "properties": { + "localComments": { + "type": "integer", + "format": "int64", + "x-go-name": "LocalComments" + }, + "localPosts": { + "type": "integer", + "format": "int64", + "x-go-name": "LocalPosts" + }, + "users": { + "$ref": "#/definitions/NodeInfoUsageUsers" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, + "NodeInfoUsageUsers": { + "description": "NodeInfoUsageUsers contains statistics about the users of this server", + "type": "object", + "properties": { + "activeHalfyear": { + "type": "integer", + "format": "int64", + "x-go-name": "ActiveHalfyear" + }, + "activeMonth": { + "type": "integer", + "format": "int64", + "x-go-name": "ActiveMonth" + }, + "total": { + "type": "integer", + "format": "int64", + "x-go-name": "Total" + } + }, + "x-go-package": "code.gitea.io/gitea/modules/structs" + }, "Note": { "description": "Note contains information related to a git note", "type": "object", @@ -17533,6 +17671,12 @@ } } }, + "NodeInfo": { + "description": "NodeInfo", + "schema": { + "$ref": "#/definitions/NodeInfo" + } + }, "Note": { "description": "Note", "schema": {