Lyo.ShortUrl 3.0.0

Lyo.ShortUrl

URL-shortening contracts: IShortUrlService, ShortUrlServiceBase for validation / metrics / error-code mapping, a default ShortUrlService that mints short codes (no storage), a fluent UrlShortenBuilder, and DTOs for shorten / expand / statistics results.

Examples

Quick start

using Lyo.ShortUrl;
using Lyo.ShortUrl.Models;

services.AddShortUrl(o => {
    o.BaseUrl = "https://short.ly";
    o.AllowCustomAliases = true;
    o.MaxAliasLength = 50;
});

var builder = UrlShortenBuilder.New()
    .SetLongUrl("https://example.com/long-url")
    .SetCustomAlias("my-alias")
    .SetExpirationDate(DateTime.UtcNow.AddDays(30));

var result = await shortUrlService.ShortenAsync(builder, ct);
// result.IsSuccess, result.ShortUrl, result.LongUrl, result.Alias, result.Errors

// Expand / stats / update / delete require a storage-backed IShortUrlService
// implementation; the in-box ShortUrlService surfaces NotSupported errors there.

Configuration (appsettings.json)

{
  "ShortUrlOptions": {
    "BaseUrl": "https://short.ly",
    "DefaultExpirationDays": 30,
    "MaxAliasLength": 50,
    "MinAliasLength": 3,
    "AllowCustomAliases": true,
    "EnableMetrics": false,
    "EnforceHttps": false
  }
}

IShortUrlService

• Task<UrlShortenResult> ShortenAsync(string longUrl, string? customAlias = null, DateTime? expirationDate = null, CancellationToken ct = default)
• Task<UrlShortenResult> ShortenAsync(UrlShortenBuilder builder, CancellationToken ct = default)
• Task<UrlExpandResult> ExpandAsync(string shortUrl, CancellationToken ct = default)
• Task<UrlStatisticsResult> GetStatisticsAsync(string shortUrl, CancellationToken ct = default)
• Task<bool> DeleteAsync(string shortUrl, CancellationToken ct = default)
• Task<UrlShortenResult> UpdateAsync(string shortUrl, string newLongUrl, CancellationToken ct = default)
• Task<bool> TestConnectionAsync(CancellationToken ct = default)

ShortUrlServiceBase

• Validates inputs (longUrl non-empty; expirationDate strictly in the future; HTTP → HTTPS rewrite when Options.EnforceHttps == true).
• Wraps ShortenAsync / ExpandAsync in metrics timers plus counters keyed off MetricNames. Override CreateMetricNamesDictionary() to rebrand.
• Maps OperationCanceledException → SHORTURL_OPERATION_CANCELLED, other exceptions → SHORTURL_*_FAILED codes.
• Supplies default NotSupportedException throws for GetStatisticsAsync, DeleteAsync, UpdateAsync, TestConnectionAsync, ShortenCoreAsync, and ExpandCoreAsync, so a partial implementation only overrides what it supports.

ShortUrlService (in-box)

• ShortenCoreAsync checks the custom alias against Options.AllowCustomAliases / MinAliasLength / MaxAliasLength and, when none is supplied, calls IShortUrlGenerator.Generate. It then returns UrlShortenResult.FromSuccess(...) with BaseUrl/{id} (or just {id} when BaseUrl is empty).
• ExpandCoreAsync, GetStatisticsAsync, and UpdateAsync return an error result with SHORTURL_EXPAND_FAILED / SHORTURL_GET_STATISTICS_FAILED / SHORTURL_UPDATE_FAILED. They require a storage-backed implementation.
• DeleteAsync throws NotSupportedException for the same reason.
• TestConnectionAsync always returns true. There is no backend to probe.

IShortUrlGenerator / ShortUrlGenerator

• string Generate(int? length = null) returns a base-62 string (a-zA-Z0-9) of the requested length. The default ShortUrlGenerator uses RandomNumberGenerator and an 8-character default length.

UrlShortenBuilder

• SetLongUrl(string longUrl, bool enforceHttps = false) runs through UriHelpers.GetValidWebUri (throws InvalidFormatException on invalid URLs). When enforceHttps, HTTP becomes HTTPS.
• SetCustomAlias(string? alias) must match ^[a-zA-Z0-9\-]+$. Passing null/whitespace clears the alias.
• SetExpirationDate(DateTime? date) must be in the future, or null.
• Clear() resets the builder.
• Build() returns (LongUrl, CustomAlias, ExpirationDate). Throws if LongUrl was never set.
• UrlShortenBuilder.New() convenience factory.

Error codes (ShortUrlErrorCodes)

SHORTURL_SHORTEN_FAILED, SHORTURL_EXPAND_FAILED, SHORTURL_GET_STATISTICS_FAILED, SHORTURL_DELETE_FAILED, SHORTURL_UPDATE_FAILED, SHORTURL_OPERATION_CANCELLED, SHORTURL_URL_NOT_FOUND, SHORTURL_URL_EXPIRED, SHORTURL_INVALID_URL, SHORTURL_ALIAS_ALREADY_EXISTS, SHORTURL_CUSTOM_ALIAS_NOT_ALLOWED, SHORTURL_INVALID_ALIAS_LENGTH.

ShortUrlServiceOptions

Service registration (Extensions)

Dependencies

Generated from ProjectReference / PackageReference (same model as docs/Lyo.ProjectGraph.html).

• Lyo.Common.Core (direct, lyo)
• Lyo.Exceptions (direct, lyo)
• Lyo.Metrics (direct, lyo)
• Lyo.Result (direct, lyo)
• Microsoft.Extensions.Configuration.Binder 10.0.5 (direct, microsoft)
• Microsoft.Extensions.DependencyInjection.Abstractions 10.0.5 (direct, microsoft)
• Microsoft.Extensions.Logging.Abstractions 10.0.5 (direct, microsoft)
• Microsoft.Extensions.Options 10.0.5 (direct, microsoft)
• Microsoft.Bcl.AsyncInterfaces 10.0.5 (transitive, microsoft, netstandard2.0)
• System.Memory 4.6.3 (transitive, microsoft, netstandard2.0)
• System.Text.Json 10.0.5 (transitive, microsoft, netstandard2.0)