Skip to content

Open-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia

feat(kernel): extensible content media types (#5244)

Shreyascaadfc8c55e8
diff --git a/packages/hoppscotch-common/src/helpers/kernel/common/content.ts b/packages/hoppscotch-common/src/helpers/kernel/common/content.ts
index c4e5cc337..9a5d103fb 100644
--- a/packages/hoppscotch-common/src/helpers/kernel/common/content.ts
+++ b/packages/hoppscotch-common/src/helpers/kernel/common/content.ts
@@ -3,20 +3,33 @@ import * as TE from "fp-ts/TaskEither"
import * as O from "fp-ts/Option"
import { pipe } from "fp-ts/function"
-import { parseJSONAs } from "~/helpers/functional/json"
import { ContentType, MediaType, content } from "@hoppscotch/kernel"
import { EffectiveHoppRESTRequest } from "~/helpers/utils/EffectiveURL"
+/**
+ * Content processors for converting raw body strings to standardized ContentType objects.
+ *
+ * If a processor is called, it's expected that it's correct content type.
+ * NOTE: Validation belongs in upper layers, not the processor layer.
+ */
const Processors = {
+ /**
+ * Processes JSON content as pre-stringified JSON text.
+ *
+ * NOTE: Assumes input is valid JSON in string format since user selected "JSON".
+ * Uses `content.text()` with JSON media type to avoid double-encoding.
+ */
json: {
process: (body: string): E.Either<Error, ContentType> =>
- pipe(
- parseJSONAs<unknown>(body),
- E.map(() => content.text(body, MediaType.APPLICATION_JSON)),
- E.orElse(() => E.right(content.text(body, MediaType.TEXT_PLAIN)))
- ),
+ E.right(content.text(body, MediaType.APPLICATION_JSON)),
},
+ /**
+ * Processes binary content from Blob/File objects.
+ *
+ * Converts Blob to Uint8Array while preserving filename and content type.
+ * Returns TaskEither since arrayBuffer() is async.
+ */
binary: {
process: (file: Blob): TE.TaskEither<Error, ContentType> =>
pipe(
@@ -34,6 +47,12 @@ const Processors = {
),
},
+ /**
+ * Processes URL-encoded form data.
+ *
+ * Takes a raw string and wraps it in the urlencoded content type.
+ * The string is expected to be already properly encoded (e.g., "key1=value1&key2=value2").
+ */
urlencoded: {
process: (body: string): E.Either<Error, ContentType> =>
pipe(
@@ -44,17 +63,33 @@ const Processors = {
),
},
+ /**
+ * Processes XML content as text with XML media type.
+ *
+ * Assumes input is valid XML string format.
+ */
xml: {
process: (body: string): E.Either<Error, ContentType> =>
E.right(content.xml(body, MediaType.APPLICATION_XML)),
},
+ /**
+ * Processes plain text content.
+ *
+ * Fallback processor for any text-based content that doesn't fit other categories.
+ */
text: {
process: (body: string): E.Either<Error, ContentType> =>
E.right(content.text(body, MediaType.TEXT_PLAIN)),
},
}
+/**
+ * Maps content type strings to appropriate processor.
+ *
+ * @param contentType - MIME type string (e.g., "application/json")
+ * @returns Processor function that converts string body to ContentType
+ */
const getProcessor = (contentType: string) => {
switch (contentType) {
case "application/json":
@@ -75,6 +110,14 @@ const getProcessor = (contentType: string) => {
}
}
+/**
+ * Transforms HTTP request body content into standardized `ContentType` objects for the `relay` system.
+ *
+ * Returns None if no body content is present or if the body type doesn't match the content type.
+ *
+ * @param request - EffectiveHoppRESTRequest containing body and content type information
+ * @returns TaskEither<Error, Option<ContentType>> - Success with optional content, or error
+ */
export const transformContent = (
request: EffectiveHoppRESTRequest
): TE.TaskEither<Error, O.Option<ContentType>> => {
diff --git a/packages/hoppscotch-kernel/src/relay/v/1.ts b/packages/hoppscotch-kernel/src/relay/v/1.ts
index d6562c16b..cef85bb82 100644
--- a/packages/hoppscotch-kernel/src/relay/v/1.ts
+++ b/packages/hoppscotch-kernel/src/relay/v/1.ts
@@ -105,14 +105,17 @@ export enum MediaType {
}
export type ContentType =
- | { kind: "text"; content: string; mediaType: MediaType.TEXT_PLAIN | MediaType.TEXT_HTML | MediaType.TEXT_CSS | MediaType.TEXT_CSV }
- | { kind: "json"; content: unknown; mediaType: MediaType.APPLICATION_JSON | MediaType.APPLICATION_LD_JSON }
- | { kind: "xml"; content: string; mediaType: MediaType.APPLICATION_XML | MediaType.TEXT_XML }
- | { kind: "form"; content: FormData; mediaType: MediaType.APPLICATION_FORM }
- | { kind: "binary"; content: Uint8Array; mediaType: MediaType.APPLICATION_OCTET | string; filename?: string }
- | { kind: "multipart"; content: FormData; mediaType: MediaType.MULTIPART_FORM }
- | { kind: "urlencoded"; content: string; mediaType: MediaType.APPLICATION_FORM }
- | { kind: "stream"; content: ReadableStream; mediaType: string }
+ | { kind: "text"; content: string; mediaType: MediaType | string }
+ | { kind: "json"; content: unknown; mediaType: MediaType | string }
+ | { kind: "xml"; content: string; mediaType: MediaType | string }
+ | { kind: "form"; content: FormData; mediaType: MediaType | string }
+ | { kind: "binary"; content: Uint8Array; mediaType: MediaType | string; filename?: string }
+ | { kind: "multipart"; content: FormData; mediaType: MediaType | string }
+ | { kind: "urlencoded"; content: string; mediaType: MediaType | string }
+ | { kind: "stream"; content: ReadableStream; mediaType: MediaType | string }
+ // TODO: Considering adding a "raw" kind for explicit pass-through content in the future,
+ // not required at the moment tho, needs some plumbing on the relay side.
+ // | { kind: "raw"; content: string; mediaType: MediaType | string }
export interface RelayResponseBody {
body: Uint8Array
@@ -526,43 +529,79 @@ export const transform = {
)
}
+/**
+ * Content factory functions for creating standardized HTTP request content.
+ *
+ * The `kind` field determines how content is processed, basically
+ * - Web (Axios + JS): `kind` is ignored, relying on Axios' auto-detect
+ * - Desktop (`relay` + Rust): `kind` routes to processing `fn` in `relay`
+ *
+ * NOTE: `mediaType` field sets the HTTP `Content-Type` header in both.
+ *
+ * There are a bunch of reasons for separating routing and `Content-Type`,
+ * see `relay` code for more info.
+ * Essentially this allows for flexible scenarios like:
+ * - Sending pre-stringified JSON as text to avoid double-encoding
+ * - Using custom vendor media types with standard processing
+ * - Future processing evolution without breaking HTTP contracts
+ */
export const content = {
+ /**
+ * Creates text content. Useful for:
+ * - Plain text
+ * - Pre-stringified JSON (to avoid encoding escapes)
+ * - Custom text formats
+ */
text: (
content: string,
- mediaType?: MediaType.TEXT_PLAIN | MediaType.TEXT_HTML | MediaType.TEXT_CSS | MediaType.TEXT_CSV
+ mediaType?: MediaType | string
): ContentType => ({
kind: "text",
content: transform.text(content),
mediaType: mediaType ?? MediaType.TEXT_PLAIN
}),
+ /**
+ * Creates JSON content with automatic serialization.
+ * Note: If you already have a JSON string, consider using `text()`
+ * with `APPLICATION_JSON` mediaType to avoid double-encoding.
+ */
json: <T>(
content: T,
- mediaType?: MediaType.APPLICATION_JSON | MediaType.APPLICATION_LD_JSON | MediaType.APPLICATION_JSON
+ mediaType?: MediaType | string
): ContentType => ({
kind: "json",
content: transform.json(content),
mediaType: mediaType ?? MediaType.APPLICATION_JSON
}),
+ /**
+ * Creates XML content. Currently processed as text.
+ */
xml: (
content: string,
- mediaType?: MediaType.APPLICATION_XML | MediaType.TEXT_XML
+ mediaType?: MediaType | string
): ContentType => ({
kind: "xml",
content: transform.xml(content),
mediaType: mediaType ?? MediaType.APPLICATION_XML
}),
- form: (content: FormData): ContentType => ({
+ /**
+ * Creates form-encoded content from FormData.
+ */
+ form: (content: FormData, mediaType?: MediaType | string): ContentType => ({
kind: "form",
content: transform.form(content),
- mediaType: MediaType.APPLICATION_FORM
+ mediaType: mediaType ?? MediaType.APPLICATION_FORM
}),
+ /**
+ * Creates binary content. Supports any binary format.
+ */
binary: (
content: Uint8Array,
- mediaType: string = MediaType.APPLICATION_OCTET,
+ mediaType: MediaType | string = MediaType.APPLICATION_OCTET,
filename?: string
): ContentType => ({
kind: "binary",
@@ -571,25 +610,92 @@ export const content = {
filename
}),
- multipart: (content: FormData): ContentType => ({
+ /**
+ * Creates multipart form content with file upload support.
+ */
+ multipart: (content: FormData, mediaType?: MediaType | string): ContentType => ({
kind: "multipart",
content: transform.multipart(content),
- mediaType: MediaType.MULTIPART_FORM
+ mediaType: mediaType ?? MediaType.MULTIPART_FORM
}),
- urlencoded: (content: string | Record<string, any>): ContentType => ({
+ /**
+ * Creates URL-encoded content from string or object.
+ */
+ urlencoded: (content: string | Record<string, any>, mediaType?: MediaType | string): ContentType => ({
kind: "urlencoded",
content: transform.urlencoded(content),
- mediaType: MediaType.APPLICATION_FORM
+ mediaType: mediaType ?? MediaType.APPLICATION_FORM
}),
- stream: (content: ReadableStream, mediaType: string): ContentType => ({
+ /**
+ * Creates streaming content for large payloads.
+ */
+ stream: (content: ReadableStream, mediaType: MediaType | string): ContentType => ({
kind: "stream",
content: transform.stream(content),
mediaType
})
+
+ // TODO: Raw content type for pass-through scenarios:
+ // raw: (content: string, mediaType: MediaType | string): ContentType => ({
+ // kind: "raw",
+ // content,
+ // mediaType
+ // })
+}
+
+/**
+ * Executable usage examples for content factory functions
+ * usage / patterns / executable guarantees.
+ *
+ * These examples show API usage patterns but also act as compile-time
+ * guarantees that the API works as documented. If the content factory functions
+ * change in breaking ways, these examples will fail to type-check,
+ * these aren't exactly docs nor tests but a mix,
+ * and these also prevent documentations drift.
+ *
+ * Pattern borrowed from Rust's documentation tests where executable code examples are
+ * embedded alongside API definitions.
+ * See: https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html
+ *
+ * Since TypeScript lacks built-in doc-tests, this provides somewhat similar
+ * guarantees, essentially serving as
+ * - discoverable docs that devs can copy-paste or import, and also
+ * - type-checked contracts so these cannot become outdated since they're actual
+ * executable code validated at compile time.
+ */
+export const examples = {
+ // Avoid double-encoding of pre-stringified JSON
+ preStringifiedJson: content.text(
+ '{"message": "Hello \\"world\\"", "path": "C:\\\\Users\\\\file.txt"}',
+ MediaType.APPLICATION_JSON
+ ),
+
+ // Vendor-specific JSON formats
+ jsonApi: content.json(
+ { data: { type: "users", id: "1" } },
+ "application/vnd.api+json"
+ ),
+
+ // Custom XML schema
+ soapXml: content.xml(
+ '<soap:Envelope>...</soap:Envelope>',
+ "application/soap+xml"
+ ),
+
+ // Custom binary format
+ customBinary: content.binary(
+ new Uint8Array([0x89, 0x50, 0x4E, 0x47]),
+ "image/png"
+ ),
+
+ // Backwards compatible - uses defaults
+ standardJson: content.json({ name: "John" }),
+ standardText: content.text("Hello world")
}
+
/**
* Helper function to convert standard `FormData` to array of arrays `[string, FormDataValue[]][]`
*