Change NodeInfo `software.version` field type from `SemVer` to `string`

[dahlia]

Summary

The NodeInfo specification does not require the software.version field to follow Semantic Versioning, but Fedify currently enforces this by using the SemVer type for this field. This causes compatibility issues with legitimate software that uses different versioning schemes (see #353 for a real-world example with snac).

Current Situation

Currently, the NodeInfo interface defines software.version as:

interface NodeInfo {
  software: {
    name: string;
    version: SemVer;  // <-- This is the problem
    // ...
  };
  // ...
}

This forces all NodeInfo implementations to use Semantic Versioning, which is not required by the NodeInfo 2.1 specification. The spec simply states that software.version is a string without any format requirements.

Proposed Change

In Fedify 2.0, change the type of software.version from SemVer to string:

interface NodeInfo {
  software: {
    name: string;
    version: string;  // <-- Plain string, as per spec
    // ...
  };
  // ...
}

Breaking Change Impact

This is a breaking change that will affect:

1. NodeInfo dispatchers — Code that creates NodeInfo objects will need to change from:

   version: { major: 1, minor: 0, patch: 0 }

   to:

   version: "1.0.0"

2. NodeInfo consumers — Code that reads NodeInfo.software.version will receive a string instead of a SemVer object, affecting any code that accesses version.major, version.minor, or version.patch.

Related Issues

• fedify nodeinfo reports snac's nodeinfo as invalid #353 — The original bug report that highlighted this design issue
• fix: change nodeinfo version fallback behavior #365 — PR implementing the immediate fix (best-effort parsing improvement)

References

• fedify nodeinfo reports snac's nodeinfo as invalid #353 (comment)
• fix: change nodeinfo version fallback behavior #365 (comment)

Alternative Considered

We considered supporting both SemVer and string via a union type (SemVer | string), but this would:

• Add complexity to the API
• Still not be spec-compliant (the spec says it's a string, period)
• Create confusion about which type to use when

Therefore, a clean break to string in a major version is the preferred approach.

[ThisIsMissEm]

Code that creates NodeInfo objects will need to change from:

Maybe code that creates can be typed as like:

NodeInfo | LegacyNodeInfo

And if we get the legacy, we can convert the object to a string under the hood?

[dahlia]

Hmm, we might be able to add one more function signature until v2.0, like:

export async function getNodeInfo(
  url: URL | string,
  options?: GetNodeInfoOptions & { parse?: "strict" | "best-effort" },
): Promise<NodeInfo | undefined>;

export async function getNodeInfo(
  url: URL | string,
  options: GetNodeInfoOptions & { parse: "legacy" },
): Promise<LegacyNodeInfo | undefined>;

export async function getNodeInfo(
  url: URL | string,
  options: GetNodeInfoOptions & { parse: "none" },
): Promise<JsonValue | undefined>;

… and then, drop the LegacyNodeInfo when we ship v2.0.

[dodok8]

I'll handle this issue. Should I work on next brach(2.0.0) or main branch(1.9.0)?

[dahlia]

@dodok8 Thanks. You should work on the next branch.

[dodok8]

@dodok8 Thanks. You should work on the next branch.

Then I won't make LegacyNodeInfo as you mentioned,

… and then, drop the LegacyNodeInfo when we ship v2.0.

[dahlia]

Yeah, you don't need to make LegacyNodeInfo.