markdown.go

package docs

import (
	"bytes"
	"fmt"
	"html"
	"regexp"
	"strings"
	"time"

	cmds "github.com/ipfs/go-ipfs-cmds"
)

// MarkdownFormatter implements a markdown doc generator. It is
// used to generate the IPFS website API reference at
// https://github.com/ipfs/website/blob/master/content/pages/docs/api.md
type MarkdownFormatter struct{}

func (md *MarkdownFormatter) GenerateIntro() string {
	buf := new(bytes.Buffer)
	fmt.Fprintf(buf, `---
title: Kubo RPC API
description: RPC API v0 reference for Kubo IPFS daemon.
---

# Kubo RPC API v0 reference

<!-- DO NOT EDIT THIS FILE.

This file is auto-generated.
Any changes you make to this file will be overwritten.


To edit this file, change the contents of the https://github.com/ipfs/ipfs-docs/blob/main/tools/http-api-docs/markdown.go template.































I AM SERIOUS, DO NOT EDIT ANYTHING BELOW ;-D

-->

::: tip Generated on %s, from kubo v%s
This document was autogenerated from [v%s](https://github.com/ipfs/kubo/releases/tag/v%s).
For issues and support, check out the [http-api-docs](https://github.com/ipfs/ipfs-docs/tree/main/tools/http-api-docs) generator on GitHub.
:::

When a Kubo IPFS node is running as a daemon, it exposes an HTTP RPC API that allows you to control the node and run the same commands you can from the command line.

In many cases, using this RPC API is preferable to embedding IPFS directly in your program — it allows you to maintain peer connections that are longer lived than your app and you can keep a single IPFS node running instead of several if your app can be launched multiple times. In fact, the `+"`ipfs`"+` CLI commands use this RPC API when operating in online mode.

::: danger NEVER EXPOSE THE RPC API TO THE PUBLIC INTERNET

The RPC API provides admin-level access to your Kubo IPFS node, including `+"`/api/v0/config`"+`.

It is bound to `+"`localhost`"+` by default on purpose. You should never expose it to the public internet, just like you would never expose a SQL database or other backend service.

If you are looking for an interface designed for browsers and public internet, consider implementation-agnostic [HTTP Gateway](../../reference/http/gateway.md) instead.
:::

## Getting started

### Alignment with CLI commands

The API under `+"`/api/v0/`"+` is an RPC-style API over HTTP, not a REST API.

[Every command](../../reference/kubo/cli.md) usable from the CLI is also available through the HTTP RPC API. For example:
`+"```sh"+
		`
> ipfs swarm peers
/ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
/ip4/104.236.151.122/tcp/4001/p2p/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx
/ip4/104.236.176.52/tcp/4001/p2p/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z

> curl -X POST http://127.0.0.1:5001/api/v0/swarm/peers
{
  "Strings": [
    "/ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
    "/ip4/104.236.151.122/tcp/4001/p2p/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx",
    "/ip4/104.236.176.52/tcp/4001/p2p/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z",
  ]
}
`+"```"+`

### Arguments

Arguments are added through the special query string key "arg":

`+"```"+`
> curl -X POST "http://127.0.0.1:5001/api/v0/swarm/disconnect?arg=/ip4/54.93.113.247/tcp/48131/p2p/QmUDS3nsBD1X4XK5Jo836fed7SErTyTuQzRqWaiQAyBYMP"
{
  "Strings": [
    "disconnect QmUDS3nsBD1X4XK5Jo836fed7SErTyTuQzRqWaiQAyBYMP success",
  ]
}
`+"```"+`

Note that it can be used multiple times to signify multiple arguments.

### Flags

Flags are added through the query string. For example, the %s flag is the %s query parameter below:

`+"```"+`
> curl -X POST "http://127.0.0.1:5001/api/v0/object/get?arg=QmaaqrHyAQm7gALkRW8DcfGX3u8q9rWKnxEMmf7m9z515w&encoding=json"
{
  "Links": [
    {
      "Name": "index.html",
      "Hash": "QmYftndCvcEiuSZRX7njywX2AGSeHY2ASa7VryCq1mKwEw",
      "Size": 1700
    },
    {
      "Name": "static",
      "Hash": "QmdtWFiasJeh2ymW3TD2cLHYxn1ryTuWoNpwieFyJriGTS",
      "Size": 2428803
    }
  ],
  "Data": "CAE="
}
`+"```"+`

Some flags may be repeated. For example, the `+"`--status`"+` flag may be reused as below:

`+"```"+`
> curl -X POST "http://127.0.0.1:5001/api/v0/pin/remote/service/ls?name=myservice&status=pinned&status=pinning"
`+"```"+`

::: tip
Some arguments may belong only to the CLI but appear here too. These usually belong to client-side processing of input, particularly in the `+"`add`"+` command.

Additionally, as a convenience certain CLI commands may allow passing repeated flags as delimited lists such as
`+"`ipfs pin remote service ls --status=pinned,pinning`"+`; however, this does not apply to the HTTP API.
:::

## HTTP status codes

Status codes used at the RPC layer are simple:

- `+"`200`"+` - The request was processed or is being processed (streaming)
- `+"`500`"+` - RPC endpoint returned an error
- `+"`400`"+` - Malformed RPC, argument type error, etc
- `+"`403`"+` - RPC call forbidden
- `+"`404`"+` - RPC endpoint doesn't exist
- `+"`405`"+` - HTTP Method Not Allowed

Status code `+"`500`"+` means that the function _does_ exist, but IPFS was not able to fulfil the request because of an error. To know that reason, you have to look at the error message that is usually returned with the body of the response (if no error, check the daemon logs).

Streaming endpoints fail as above, unless they have started streaming. That means they will have sent a `+"`200`"+` status code already. If an error happens during the stream, it will be included in a Trailer response header (some endpoints may additionally include an error in the last streamed object).

A `+"`405`"+` error may mean that you are using the wrong HTTP method (i.e. GET instead of POST), and a `+"`403`"+` error occurs in a browser due to Origin / CORS.

## Origin-based security

When a request is sent from a browser, HTTP RPC API follows the [Origin-based security model](https://en.wikipedia.org/wiki/Same-origin_policy), and expects the `+"`Origin`"+` HTTP header to be present.
The API will return HTTP Error 403 when Origin is missing, does not match the API port, or is not safelisted via `+"`API.HTTPHeaders.Access-Control-Allow-Origin`"+` in the config.

`,
		time.Now().Format("2006-01-02"),
		IPFSVersion(),
		IPFSVersion(),
		IPFSVersion(),
		"`--encoding=json`",
		"`&encoding=json`")

	return buf.String()
}

func (md *MarkdownFormatter) GenerateStatusIntro(status cmds.Status) string {
	return fmt.Sprintf(`
## %s RPC commands

%s

`, statusLabel(status), statusDescription(status))
}

func statusLabel(status cmds.Status) string {
	switch status {
	case cmds.Active:
		return ""
	case cmds.Deprecated:
		return "Deprecated"
	case cmds.Experimental:
		return "Experimental"
	case cmds.Removed:
		return "Removed"
	default:
		panic("unknown command status")
	}
}

func statusDescription(status cmds.Status) string {
	switch status {
	case cmds.Active:
		return ""
	case cmds.Deprecated:
		return "Below commands are deprecated and will be removed in the future."
	case cmds.Experimental:
		return "Below commands are experimental and should be used with care. The API may change in future releases."
	case cmds.Removed:
		return "Below commands were removed, listing them here only for documentation purposes."
	default:
		panic("unknown command status")
	}
}

func statusInfobox(status cmds.Status) string {
	switch status {
	case cmds.Active:
		return "" // noop
	case cmds.Deprecated, cmds.Experimental, cmds.Removed:
		st := statusLabel(status)
		return fmt.Sprintf(`
::: warning %s

This command is %s.

:::
`, strings.ToUpper(st), strings.ToLower(st))
	default:
		panic("unknown command status")
	}
}

func (md *MarkdownFormatter) GenerateIndex(endps []*Endpoint) string {
	buf := new(bytes.Buffer)
	fmt.Fprintf(buf, "## Index\n\n")

	for _, endp := range endps {
		fmt.Fprintf(buf, "  *  [%s](#%s)\n",
			strings.TrimPrefix(endp.Name, "/api/v0"),
			strings.Replace(strings.TrimPrefix(endp.Name, "/"), "/", "-", -1))
	}

	buf.WriteString("\n\n## Endpoints\n\n")
	return buf.String()
}

func (md *MarkdownFormatter) GenerateEndpointBlock(endp *Endpoint) string {
	buf := new(bytes.Buffer)
	fmt.Fprintf(buf, `

## %s
%s
%s

`, endp.Name, statusInfobox(endp.Status), html.EscapeString(endp.Description))
	return buf.String()
}

func (md *MarkdownFormatter) GenerateArgumentsBlock(args []*Argument, opts []*Argument) string {
	buf := new(bytes.Buffer)
	fmt.Fprintf(buf, "### Arguments\n\n")

	if len(args)+len(opts) == 0 {
		fmt.Fprint(buf, "This endpoint takes no arguments.\n")
	}

	for _, arg := range args {
		fmt.Fprint(buf, genArgument(arg, true))
	}
	for _, opt := range opts {
		fmt.Fprint(buf, genArgument(opt, false))
	}

	fmt.Fprintf(buf, "\n")
	return buf.String()
}

// Removes the "Default:..." part in the descriptions.
var fixDesc, _ = regexp.Compile(` Default: [a-zA-z0-9-_]+ ?\.`)

func genArgument(arg *Argument, aliasToArg bool) string {
	// These get handled by GenerateBodyBlock
	if arg.Type == "file" {
		return "\n"
	}

	buf := new(bytes.Buffer)
	alias := arg.Name
	if aliasToArg {
		alias = "arg"
	}

	fixedDescription := string(fixDesc.ReplaceAll([]byte(arg.Description), []byte("")))
	fixedDescription = html.EscapeString(fixedDescription)

	fmt.Fprintf(buf, "- `%s` [%s]: %s", alias, arg.Type, fixedDescription)
	if len(arg.Default) > 0 {
		fmt.Fprintf(buf, " Default: `%s`.", arg.Default)
	}
	if arg.Required {
		fmt.Fprintf(buf, ` Required: **yes**.`)
	} else {
		fmt.Fprintf(buf, ` Required: no.`)
	}
	fmt.Fprintln(buf)
	return buf.String()
}

func (md *MarkdownFormatter) GenerateBodyBlock(args []*Argument) string {
	var bodyArg *Argument
	for _, arg := range args {
		if arg.Type == "file" {
			bodyArg = arg
			break
		}
	}

	if bodyArg != nil {
		buf := new(bytes.Buffer)
		fmt.Fprintf(buf, `
### Request Body

Argument `+"`%s`"+` is of file type. This endpoint expects one or several files (depending on the command) in the body of the request as 'multipart/form-data'.

`, bodyArg.Name)

		// Special documentation for /add
		if bodyArg.Endpoint == "/api/v0/add" {
			fmt.Fprintln(buf, `

The `+"`add`"+` command not only allows adding files, but also uploading directories and complex hierarchies.

This happens as follows: Every part in the multipart request is a *directory* or a *file* to be added to IPFS.

Directory parts have a special content type `+"`application/x-directory`"+`. These parts do not carry any data. The part headers look as follows:

`+"```"+`
Content-Disposition: form-data; name="file"; filename="folderName"
Content-Type: application/x-directory
`+"```"+`

File parts carry the file payload after the following headers:

`+"```"+`
Abspath: /absolute/path/to/file.txt
Content-Disposition: form-data; name="file"; filename="folderName%2Ffile.txt"
Content-Type: application/octet-stream

...contents...
`+"```"+`

The above file includes its path in the "folderName/file.txt" hierarchy and IPFS will therefore be able to add it inside "folderName". The parts declaring the directories are optional when they have files inside and will be inferred from the filenames. In any case, a depth-first traversal of the directory tree is recommended to order the different parts making the request.

The `+"`Abspath`"+` header is included for filestore/urlstore features that are enabled with the `+"`nocopy`"+` option and it can be set to the location of the file in the filesystem (within the IPFS root), or to its full web URL.
`)
		}
		return buf.String()
	}
	return ""
}

func (md *MarkdownFormatter) GenerateResponseBlock(response string) string {
	buf := new(bytes.Buffer)
	fmt.Fprintf(buf, `
### Response

On success, the call to this endpoint will return with 200 and the following body:

`)

	buf.WriteString("```json\n" + response + "\n```\n\n")

	return buf.String()
}

func (md *MarkdownFormatter) GenerateExampleBlock(endp *Endpoint) string {
	buf := new(bytes.Buffer)
	fmt.Fprintf(buf, "### cURL Example\n\n")
	fmt.Fprintf(buf, "`")
	fmt.Fprintf(buf, "curl -X POST ")

	// Assemble arguments which are not of type file
	var queryargs []string
	hasFileArg := false
	for _, arg := range endp.Arguments {
		q := "arg="
		if arg.Type != "file" {
			q += "<" + arg.Name + ">"
			queryargs = append(queryargs, q)
		} else {
			hasFileArg = true
		}
	}

	// Assemble options
	for _, opt := range endp.Options {
		q := opt.Name + "="
		//if !opt.Required { // Omit non required options
		//	continue
		//}
		if len(opt.Default) > 0 {
			q += opt.Default
		} else {
			q += "<value>"
		}
		queryargs = append(queryargs, q)
	}

	if hasFileArg {
		fmt.Fprintf(buf, "-F file=@myfile ")
	}

	fmt.Fprintf(buf, "\"http://127.0.0.1:5001%s", endp.Name)
	if len(queryargs) > 0 {
		fmt.Fprintf(buf, "?%s\"", strings.Join(queryargs, "&"))
	} else {
		fmt.Fprintf(buf, "\"")
	}

	fmt.Fprintf(buf, "`\n\n---\n")
	return buf.String()
}