from starlette.exceptions import HTTPException as StarletteHTTPException
from starlette.exceptions import WebSocketException as StarletteWebSocketException


class EndpointContext(TypedDict, total=False):
    function: str
    path: str
    file: str
    line: int


class HTTPException(StarletteHTTPException):
    """
    An HTTP exception you can raise in your own code to show errors to the client.

    @JvmField val PSEUDO_PREFIX: ByteString = ":".encodeUtf8()

    const val RESPONSE_STATUS_UTF8 = ":status"
    const val TARGET_METHOD_UTF8 = ":method"
    const val TARGET_PATH_UTF8 = ":path"
    const val TARGET_SCHEME_UTF8 = ":scheme"
    const val TARGET_AUTHORITY_UTF8 = ":authority"

    @JvmField val RESPONSE_STATUS: ByteString = RESPONSE_STATUS_UTF8.encodeUtf8()

# OpenAPI 回呼 { #openapi-callbacks }

你可以建立一個含有「路徑操作（path operation）」的 API，該操作會觸發對某個「外部 API（external API）」的請求（通常由使用你 API 的同一位開發者提供）。

當你的 API 應用呼叫「外部 API」時發生的過程稱為「回呼（callback）」。因為外部開發者撰寫的軟體會先向你的 API 發出請求，接著你的 API 再「回呼」，也就是向（可能同一位開發者建立的）外部 API 發送請求。

在這種情況下，你可能想要文件化說明該外部 API 應該長什麼樣子。它應該有哪些「路徑操作」、應該接受什麼 body、應該回傳什麼 response，等等。

## 帶有回呼的應用 { #an-app-with-callbacks }

我們用一個例子來看。

想像你開發了一個允許建立發票的應用。

這些發票會有 `id`、`title`（可選）、`customer` 和 `total`。

// along with this program.  If not, see <http://www.gnu.org/licenses/>.

package cmd

import (
	"bytes"
	"context"
	"errors"
	"fmt"
	"io"
	"net/http"
	"os"
	"path"
	"strings"
	"sync"
	"time"

	"github.com/minio/madmin-go/v3"
	"github.com/minio/minio-go/v7"
	"github.com/minio/minio-go/v7/pkg/credentials"
	xioutil "github.com/minio/minio/internal/ioutil"

// along with this program.  If not, see <http://www.gnu.org/licenses/>.

package target

import (
	"context"
	"crypto/tls"
	"encoding/json"
	"errors"
	"fmt"
	"net/url"
	"os"
	"path/filepath"

	"github.com/nsqio/go-nsq"

	"github.com/minio/minio/internal/event"
	"github.com/minio/minio/internal/logger"
	"github.com/minio/minio/internal/once"
	"github.com/minio/minio/internal/store"

		HealID:            h.HealID,
		Endpoint:          h.Endpoint,
		PoolIndex:         h.PoolIndex,
		SetIndex:          h.SetIndex,
		DiskIndex:         h.DiskIndex,
		Finished:          h.Finished,
		Path:              h.Path,
		Started:           h.Started.UTC(),
		LastUpdate:        h.LastUpdate.UTC(),
		ObjectsTotalCount: h.ObjectsTotalCount,
		ObjectsTotalSize:  h.ObjectsTotalSize,
		ItemsHealed:       h.ItemsHealed,

				for b.Loop() {
					// Load...
					xl = xlMetaV2{}
					err := xl.Load(enc)
					if err != nil {
						b.Fatal(err)
					}
					// List...
					_, err = xl.ToFileInfo("volume", "path", ids[rng.Intn(size)], false, true)
					if err != nil {
						b.Fatal(err)
					}
				}
			})
			b.Run("ListVersions", func(b *testing.B) {
				b.SetBytes(int64(size))
				b.ResetTimer()

fs.s3a.access.key=minio
fs.s3a.secret.key=minio123
fs.s3a.path.style.access=true
fs.s3a.block.size=512M
fs.s3a.buffer.dir=${hadoop.tmp.dir}/s3a
fs.s3a.committer.magic.enabled=false
fs.s3a.committer.name=directory
fs.s3a.committer.staging.abort.pending.uploads=true
fs.s3a.committer.staging.conflict-mode=append
fs.s3a.committer.staging.tmp.path=/tmp/staging
fs.s3a.committer.staging.unique-filenames=true

            pyproject.toml
            uv.lock
      - run: uv sync --locked --no-dev --group github-actions
      - uses: actions/download-artifact@v8
        with:
          name: coverage-html
          path: htmlcov
          github-token: ${{ secrets.GITHUB_TOKEN }}
          run-id: ${{ github.event.workflow_run.id }}
      # Try 5 times to upload coverage to smokeshow
      - name: Upload coverage to Smokeshow
        run: |

def create_invoice(invoice: Invoice, callback_url: HttpUrl | None = None):
    """
    Create an invoice.

    This will (let's imagine) let the API user (some external developer) create an
    invoice.

    And this path operation will:

    * Send the invoice to the client.
    * Collect the money from the client.
    * Send a notification back to the API user (the external developer), as a callback.