// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! `zfj package ...`: an owner's packages. //! //! Uploading is not an operation of the specification: each registry speaks //! the protocol of the package manager it serves, under //! `/api/packages///...` beside the API rather than inside it. //! The generic registry is the simplest of them -- a file is put at //! `//` and fetched back from the same URL -- and is the //! one supported here. const std = @import("std"); const Io = std.Io; const zfj = @import("zfj"); const args = @import("args.zig"); const call = @import("call.zig"); const Context = @import("Context.zig"); const Exit = Context.Exit; const porcelain = @import("porcelain.zig"); const Runner = porcelain.Runner; pub const commands = [_]porcelain.Command{ Runner("package", Upload).command("upload", "upload a file to the generic registry"), }; pub fn main(ctx: *Context, words: []const []const u8) !Exit { return porcelain.dispatch(ctx, "package", &commands, words); } /// Generous for a release artifact, and still a bound on what is read into /// memory to be sent. const max_file_size = 1 << 30; const Upload = struct { name: []const u8, version: []const u8, file: ?[]const u8 = null, @"source-url": ?[]const u8 = null, as: ?[]const u8 = null, owner: ?[]const u8 = null, link: ?[]const u8 = null, force: bool = false, json: bool = false, pub const short = .{ .o = "owner", .f = "force" }; pub const positional: []const []const u8 = &.{ "name", "version", "file" }; pub const usage = "upload ( | --source-url ) [--as ] [-o ] [--link ] [--force] [--json]"; pub const about = "Uploads a file to an owner's generic package registry, as //, and prints the URL it can be downloaded from. The file is read from disk, or with --source-url downloaded first. A file already there is an error, unless --force is given, which deletes it and uploads this one in its place."; pub const notes = [_]args.Note{ .{ .description = "the package's name: letters, digits and - _ + ." }, .{ .description = "the package's version" }, .{ .description = "the file to upload", .complete = .files }, .{ .description = "download the file to upload from this URL, rather than reading one from disk" }, .{ .description = "the name to upload it as (default: the file's own name, or the last part of the URL's path)" }, .{ .description = "the user or organization the package belongs to; without it, the owner of the clone's upstream or origin remote" }, .{ .description = "link the package to this repository of the owner's, so that it is listed with it" }, .{ .description = "replace the file if the version already has one of that name" }, .{ .description = "write what was uploaded, and where, as JSON rather than text for reading" }, }; pub fn run(ctx: *Context, o: Upload) !Exit { if (!validName(o.name)) return ctx.usage("'{s}' is not a package name; use letters, digits and - _ + .", .{o.name}); if (!validVersion(o.version)) return ctx.usage("'{s}' is not a version; it cannot be empty, hold a /, or begin or end with a space", .{o.version}); const Source = union(enum) { path: []const u8, url: []const u8 }; const source: Source = if (o.file) |path| blk: { if (o.@"source-url" != null) return ctx.usage("give a or --source-url, not both", .{}); break :blk .{ .path = path }; } else if (o.@"source-url") |url| .{ .url = url } else return ctx.usage("give a to upload, or a --source-url to download it from", .{}); const uri: ?std.Uri = switch (source) { .path => null, .url => |url| std.Uri.parse(url) catch return ctx.usage("'{s}' is not a URL", .{url}), }; if (uri) |u| if (!std.mem.eql(u8, u.scheme, "https") and !std.mem.eql(u8, u.scheme, "http")) return ctx.usage("--source-url takes an http or https URL, not '{s}'", .{o.@"source-url".?}); const filename = o.as orelse switch (source) { .path => |path| std.fs.path.basename(path), .url => try urlBasename(ctx.arena, uri.?), }; if (!validFilename(filename)) return ctx.usage("'{s}' cannot be uploaded as a file's name; give another with --as", .{filename}); if (o.link) |repo| if (repo.len == 0 or std.mem.findScalar(u8, repo, '/') != null) return ctx.usage("--link takes the name of one of the owner's repositories, not '{s}'", .{repo}); const owner = o.owner orelse (ctx.remoteRepository(.flag) catch |e| switch (e) { error.Usage => return ctx.usage("name the owner with -o ", .{}), error.Environment => return .environment, }).owner; const bytes = switch (source) { .path => |path| Io.Dir.cwd().readFileAlloc(ctx.io, path, ctx.arena, .limited(max_file_size)) catch |err| return ctx.usage("cannot read {s}: {s}", .{ path, @errorName(err) }), .url => |url| switch (try download(ctx, url, uri.?)) { .ok => |ok| ok, .failed => |exit| return exit, }, }; const client = ctx.client() catch return .environment; const url = try fileUrl(ctx.arena, client.base_url, owner, o.name, o.version, filename); switch (try put(ctx, client, url, bytes)) { .created => {}, .failed => |exit| return exit, .exists => { if (!o.force) return ctx.usage( "{s} {s} of {s} already has a file {s}; --force replaces it", .{ o.name, o.version, owner, filename }, ); if (try send(ctx, client, .DELETE, url, null)) |exit| return exit; switch (try put(ctx, client, url, bytes)) { .created => {}, .failed => |exit| return exit, .exists => return ctx.environment("{s} was deleted, and is still there", .{url}), } }, } if (o.link) |repo| if (call.done(ctx, "linkPackage", zfj.linkPackageRaw(client, .{ .owner = owner, .type = "generic", .name = o.name, .repo_name = repo, }))) |exit| return exit; var digest: [std.crypto.hash.sha2.Sha256.digest_length]u8 = undefined; std.crypto.hash.sha2.Sha256.hash(bytes, &digest, .{}); const sha256 = std.fmt.bytesToHex(digest, .lower); if (o.json) { try ctx.stdout.print("{f}\n", .{std.json.fmt(.{ .owner = owner, .type = "generic", .name = o.name, .version = o.version, .file = filename, .size = bytes.len, .sha256 = &sha256, .url = url, .linked_to = o.link, }, .{})}); } else { try ctx.stdout.print("{s}\n", .{url}); } try ctx.stdout.flush(); return .ok; } }; /// Fetches what is to be uploaded. The instance's token is never sent: the /// source is somewhere else, so it gets a client of its own. fn download(ctx: *Context, url: []const u8, uri: std.Uri) !call.Got([]u8) { var http: std.http.Client = .{ .allocator = ctx.gpa, .io = ctx.io }; defer http.deinit(); var body: Io.Writer.Allocating = .init(ctx.arena); if (ctx.global.debug) ctx.stderr.print("zfj: > GET {s}\n", .{url}) catch {}; const result = http.fetch(.{ .location = .{ .uri = uri }, .response_writer = &body.writer, // The bytes as they were published, not as a server chose to send them. .headers = .{ .accept_encoding = .{ .override = "identity" } }, }) catch |err| return .{ .failed = ctx.transport(url, err) }; if (ctx.global.debug) ctx.stderr.print("zfj: < {d} {s}, {d} bytes\n", .{ @backingInt(result.status), result.status.phrase() orelse "", body.written().len }) catch {}; if (result.status.class() != .success) { _ = ctx.environment("cannot download {s}: HTTP {d} {s}", .{ url, @backingInt(result.status), result.status.phrase() orelse "" }); return .{ .failed = .environment }; } if (body.written().len > max_file_size) return .{ .failed = ctx.usage("{s} is larger than zfj will upload", .{url}) }; return .{ .ok = body.written() }; } /// The last part of a URL's path, decoded: the name a file downloaded from /// it would be given. fn urlBasename(arena: std.mem.Allocator, uri: std.Uri) ![]const u8 { const path = try uri.path.toRawMaybeAlloc(arena); const trimmed = std.mem.trimEnd(u8, path, "/"); return trimmed[if (std.mem.findScalarLast(u8, trimmed, '/')) |slash| slash + 1 else 0..]; } const Put = union(enum) { created, /// The version already has a file of that name. exists, failed: Exit, }; fn put(ctx: *Context, client: *zfj.Client, url: []const u8, bytes: []const u8) !Put { var raw = request(ctx, client, .PUT, url, bytes) catch |err| return .{ .failed = ctx.transport("upload", err) }; defer raw.deinit(); if (raw.status == .conflict) return .exists; if (raw.status.class() != .success) return .{ .failed = ctx.apiError("upload", raw.status, raw.body) }; return .created; } /// Null when the request succeeded. fn send(ctx: *Context, client: *zfj.Client, method: std.http.Method, url: []const u8, body: ?[]const u8) !?Exit { var raw = request(ctx, client, method, url, body) catch |err| return ctx.transport(@tagName(method), err); defer raw.deinit(); if (raw.status.class() != .success) return ctx.apiError(@tagName(method), raw.status, raw.body); return null; } fn request(ctx: *Context, client: *zfj.Client, method: std.http.Method, url: []const u8, body: ?[]const u8) !zfj.RawResponse { var headers: std.ArrayList(std.http.Header) = .empty; if (client.api_key.len != 0) try headers.append(ctx.arena, .{ .name = "Authorization", .value = try std.fmt.allocPrint(ctx.arena, "token {s}", .{client.api_key}) }); return zfj.requestRawWithContentTypeAndExtraHeaders(client, method, url, body, "application/octet-stream", headers.items); } /// Where a generic package's file lives: beside the API, not in it. The /// client's base URL always ends in `/api/v1`. fn fileUrl( arena: std.mem.Allocator, base_url: []const u8, owner: []const u8, name: []const u8, version: []const u8, filename: []const u8, ) ![]const u8 { const api = std.mem.trimEnd(u8, base_url, "/"); const root = if (std.mem.endsWith(u8, api, "/api/v1")) api[0 .. api.len - "/api/v1".len] else api; var out: Io.Writer.Allocating = .init(arena); try out.writer.print("{s}/api/packages/", .{root}); for ([_][]const u8{ owner, "generic", name, version }) |segment| { try std.Uri.Component.percentEncode(&out.writer, segment, isSegmentChar); try out.writer.writeByte('/'); } try std.Uri.Component.percentEncode(&out.writer, filename, isSegmentChar); return out.written(); } /// The characters a path segment can carry as they are: RFC 3986's pchar. /// A `+` stays a `+`, which a version such as `1.0+build` is full of. fn isSegmentChar(c: u8) bool { return std.ascii.isAlphanumeric(c) or switch (c) { '-', '.', '_', '~', '!', '$', '&', '\'', '(', ')', '*', '+', ',', ';', '=', ':', '@' => true, else => false, }; } /// Forgejo's rule for a generic package's name. fn validName(name: []const u8) bool { if (name.len == 0) return false; for (name) |c| if (!(std.ascii.isAlphanumeric(c) or c == '-' or c == '_' or c == '+' or c == '.')) return false; return true; } fn validVersion(version: []const u8) bool { if (version.len == 0) return false; if (std.mem.trim(u8, version, " \t\r\n").len != version.len) return false; return std.mem.findScalar(u8, version, '/') == null; } fn validFilename(filename: []const u8) bool { if (filename.len == 0 or std.mem.eql(u8, filename, ".") or std.mem.eql(u8, filename, "..")) return false; for (filename) |c| if (c == '/' or c == '\\' or c < 0x20) return false; return true; } const testing = std.testing; test "every command compiles" { for (commands) |command| _ = command.run; } test "every command's notes cover its options" { try testing.expectEqual(@typeInfo(Upload).@"struct".field_names.len, Upload.notes.len); } test "a generic file's URL sits beside the API, its segments encoded" { var arena: std.heap.ArenaAllocator = .init(testing.allocator); defer arena.deinit(); const a = arena.allocator(); try testing.expectEqualStrings( "https://git.jcollie.dev/api/packages/jeff/generic/conpty/1.25.261109001/microsoft.windows.console.conpty.1.25.261109001.zip", try fileUrl(a, "https://git.jcollie.dev/api/v1", "jeff", "conpty", "1.25.261109001", "microsoft.windows.console.conpty.1.25.261109001.zip"), ); try testing.expectEqualStrings( "https://example.org/forge/api/packages/jeff/generic/a+b/1.0+build/my%20file%23.zip", try fileUrl(a, "https://example.org/forge/api/v1/", "jeff", "a+b", "1.0+build", "my file#.zip"), ); } test "a URL's file is named by the last part of its path" { var arena: std.heap.ArenaAllocator = .init(testing.allocator); defer arena.deinit(); const a = arena.allocator(); try testing.expectEqualStrings( "microsoft.windows.console.conpty.1.25.261109001.nupkg", try urlBasename(a, try std.Uri.parse("https://api.nuget.org/v3-flatcontainer/microsoft.windows.console.conpty/1.25.261109001/microsoft.windows.console.conpty.1.25.261109001.nupkg?x=1")), ); try testing.expectEqualStrings("my file.zip", try urlBasename(a, try std.Uri.parse("https://example.org/d/my%20file.zip"))); try testing.expectEqualStrings("", try urlBasename(a, try std.Uri.parse("https://example.org"))); } test "names, versions and filenames Forgejo would refuse are caught first" { try testing.expect(validName("conpty")); try testing.expect(validName("a_b-c+d.e")); try testing.expect(!validName("")); try testing.expect(!validName("a/b")); try testing.expect(!validName("a b")); try testing.expect(validVersion("1.25.261109001")); try testing.expect(!validVersion("")); try testing.expect(!validVersion(" 1.0")); try testing.expect(!validVersion("1/0")); try testing.expect(validFilename("conpty.zip")); try testing.expect(!validFilename("..")); try testing.expect(!validFilename("a/b.zip")); }